1 #ident "%Z%%M% %I% %E% SMI" mwc
2
3 CDDL HEADER START
4
5 The contents of this file are subject to the terms of the
6 Common Development and Distribution License, Version 1.0 only
7 (the "License"). You may not use this file except in compliance
8 with the License.
9
10 You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
11 or http://www.opensolaris.org/os/licensing.
12 See the License for the specific language governing permissions
13 and limitations under the License.
14
15 When distributing Covered Code, include this CDDL HEADER in each
16 file and include the License file at usr/src/OPENSOLARIS.LICENSE.
17 If applicable, add the following below this CDDL HEADER, with the
18 fields enclosed by brackets "[]" replaced with your own identifying
19 information: Portions Copyright [yyyy] [name of copyright owner]
20
21 CDDL HEADER END
22
23 Enterprise: Public Layer Test Specification
24 ===========================================
25
26 ABSTRACT
27
28 This document describes a test specification intended to be used
29 in the development of tests designed to validate the service provider
30 layer API described in Section 2.2 of the Enterprise DHCP Service
31 Architecture Specification (ARCH) [1]. The first test is a basic sanity
32 test, designed to verify that the API works as designed when fed data
33 in the correct form. The second test is a full test, which compliments
34 the basic sanity test by providing cases which test the stability and
35 MT-safeness of the API.
36
37 TEST APPLICATION
38
39 Test suite(s) written to this specification should be run on
40 every available public module on the reference platform of each of the
41 supported architectures (sparcv8, sparcv9, IA32, IA64) for each build
42 of the ON consolidation. See "Enterprise Reference platforms" [2] for
43 more information.
44
45 TEST PREPARATION
46
47 The packages SUNWdhc{df,db,dn} containing the public module(s)
48 under test need to be installed in /usr/lib/inet/dhcp/svc on the machine
49 under test. The data service(s) (if necessary) which hosts the data
50 store must be configured and running. A data store container directory
51 (location) within the data service must exist and be empty. The machine
52 under test must have the appropriate authorization (root user) for
53 accessing the hosting data service. Note that it is important to note
54 whether the data service is hosted on the test machine, or whether the
55 data service is hosted on a different machine and the machine under
56 test is a client of that data service. Where the data service is hosted
57 will have an affect on the test results, particularly performance.
58
59 BASIC SANITY TEST
60
61 Description
62
63 This test validates the basic operation of service
64 provider layer API function calls when presented with valid
65 arguments in a valid run environment. It is implemented as a
66 multithreaded program running a single thread to exercise the API
67 referenced in Section 2.2 of ARCH [1]. This program should create
68 dhcptab and dhcp network containers within the data store, and
69 exercise the *_dt and *_dn calls to add, modify, and delete
70 multiple records. The result of the add, modify, and delete
71 operations must be validated between each operation. The program
72 should be written such that the initial condition described under
73 TEST PREPARATION is restored. Operations are PASS/FAIL, and must
74 be compared against a human-verified expect file.
75
76 Test Data
77
78 Item Description Application
79 ==== =========== ===========
80 <location> Public module specific status, list,
81 path name to container open_dt,
82 directory (e.g. /var/dhcp remove_dt,
83 for 'files' data store). open_dn,
84 remove_dn
85
86 <Server IP> System under test's IP N/A
87 address.
88
89 dt records As follows: *_dt
90
91 SrootOpt s Vendor=SUNW.Ultra-1 SUNW.i86pc,1,ASCII,1,0
92 SrootIP4 s Vendor=SUNW.Ultra-1 SUNW.i86pc,2,IP,1,1
93 SrootNM s Vendor=SUNW.Ultra-1 SUNW.i86pc,3,ASCII,1,0
94 SrootPTH s Vendor=SUNW.Ultra-1 SUNW.i86pc,4,ASCII,1,0
95 SswapIP4 s Vendor=SUNW.Ultra-1 SUNW.i86pc,5,IP,1,1
96 SswapPTH s Vendor=SUNW.Ultra-1 SUNW.i86pc,6,ASCII,1,0
97 SbootFIL s Vendor=SUNW.Ultra-1 SUNW.i86pc,7,ASCII,1,0
98 Stz s Vendor=SUNW.Ultra-1 SUNW.i86pc,8,ASCII,1,0
99 SbootRS s Vendor=SUNW.Ultra-1 SUNW.i86pc,9,NUMBER,2,1
100 SinstIP4 s Vendor=SUNW.Ultra-1 SUNW.i86pc,10,IP,1,1
101 SinstNM s Vendor=SUNW.Ultra-1 SUNW.i86pc,11,ASCII,1,0
102 SinstPTH s Vendor=SUNW.Ultra-1 SUNW.i86pc,12,ASCII,1,0
103 SsysidCF s Vendor=SUNW.Ultra-1 SUNW.i86pc,13,ASCII,1,0
104 SjumpsCF s Vendor=SUNW.Ultra-1 SUNW.i86pc,14,ASCII,1,0
105 Sterm s Vendor=SUNW.Ultra-1 SUNW.i86pc,15,ASCII,1,0
106 Locale m :UTCoffst=-18000:
107 Solaris m :SrootIP4=129.148.174.27:SrootNM="atlantic": \
108 :SinstIP4=129.148.174.27:SinstNM="atlantic": \
109 :Sterm="xterm":BootSrvA=129.148.174.27:
110 sparc m \
111 :SrootPTH="/export/s28/solaris1of2.s28s_wos/latest/Solaris_8/Tools/Boot": \
112 :SinstPTH="/export/s28/solaris1of2.s28s_wos/latest":
113 sun4u m :Include=Solaris:Include=sparc:
114 i86pc m :Include=Solaris:SbootFIL="/platform/i86pc/kernel/unix": \
115 :SinstPTH="/export/s28/solaris1of2.s28x_wos/latest": \
116 :SrootPTH="/export/s28/solaris1of2.s28x_wos/latest/Solaris_8/Tools/Boot":
117 SUNW.i86pc m :Include=i86pc:
118 SUNW.Ultra-1 m :SbootFIL="/platform/sun4u/kernel/sparcv9/unix": \
119 :Include=sun4u:
120 172.21.0.0 m :Subnet=255.255.0.0:Router=172.21.0.2: \
121 :Broadcst=172.21.255.255:
122 atlantic m :Include=Locale:Timeserv=129.148.174.27:LeaseTim=3600: \
123 :LeaseNeg:Hostname:DNSdmain="snt.east.sun.com": \
124 :DNSserv=172.21.0.1:
125 010800207E8A02 m :Impress=172.22.255.27:
126
127
128 172.21.0.0 Dhcp network container. *_dn
129
130 dn records ~3000, as follows: *_dn
131
132 00 00 172.21.0.6 <Server IP> 0 atlantic
133 .
134 .
135 .
136 00 00 172.21.12.6 <Server IP> 0 atlantic
137
138 Generic Data Store Status
139 =========================
140
141 Case #1 status:
142
143 Call function with <location>. PASS if DSVC_SUCCESS is
144 returned, FAIL otherwise. If this case fails, abort the test.
145
146 Case #2 version:
147
148 Call function. Version value returned must be one (1)
149 for PASS. If this case fails, abort the test.
150
151 Case #3 capability:
152
153 Call function. Compare returned capability against
154 confirmed capability known for the public module under test.
155 Match is PASS.
156
157 Case #4 list:
158
159 Call function with <location>. PASS if DSVC_NOENT is
160 returned, listppp is NULL, and count is set to 0. As part of
161 Test preparation, there should be *no* containers of any kind in
162 the underlying data service of the public module. If this case
163 fails, abort the test.
164
165 dhcptab Container API
166 =====================
167
168 Case #5 alloc_dtrec:
169
170 Call function, verify that a non-NULL dt_rec_t pointer
171 is returned. Free result with free_dtrec.
172
173 Case #6 open_dt:
174
175 Create a dhcptab at <location> specifying DSVC_CREATE |
176 DSVC_READ | DSVC_WRITE. Preserve handpp for use in the following
177 cases. PASS if DSVC_SUCCESS is returned, abort the test
178 otherwise.
179
180 Case #7 add_dt:
181
182 7.1. Initialize container.
183
184 Using the handle returned in case #6, add the
185 dhcptab test records to the dhcptab. Verify that the
186 dhcptab exists by calling list.
187
188 7.2. Attempt to add duplicate record.
189
190 Attempt to add the SbootRS symbol definition and
191 172.21.0.0 macro definition to the dhcptab container.
192 PASS if DSVC_EXISTS is returned in both cases.
193
194 Case #8 lookup_dt:
195
196 8.1. Verify case #7.
197
198 Using a count value of -1 and a "query" value
199 initialized by DSVC_QINIT (Figure 5 of ARCH[1]), verify
200 that the contents of the dhcptab container match the
201 test data. Note that the order of the records returned
202 may not be the same as the order in which they were
203 added in case #7.
204
205 8.2 Verify dhcptab container type.
206
207 8.2.1. Look for all records with a DT_QTYPE
208 value of "s". Verify that only the "s" type
209 records are returned.
210
211 8.2.2. Look for all records with a DT_QTYPE
212 value of "m". Verify that only the "m" type
213 records are returned.
214
215 8.2.3. Look for DT_QKEY of "atlantic". Verify
216 that only the macro "atlantic" is returned, and
217 the value is correct.
218
219 8.2.4. Look for DTQKEY of i86pc and not a
220 DT_QTYPE of "m". Verify that only the macro
221 "i86pc" is returned.
222
223 Case #9 modify_dt:
224
225 9.1 Modify dhcptab container records
226
227 9.1.1. Using lookup_dt to find the record with a
228 DT_QKEY of "Sterm", change the name of the
229 record from "Sterm" to "sTERM". Use lookup_dt to
230 verify that the original record has been
231 renamed.
232
233 9.1.2. Using lookup_dt to find the record with a
234 DT_QKEY of "Solaris", change the value portion
235 of the record to be:
236
237 :SrootIP4=129.148.174.27:SrootNM="atlantic": \
238 :SinstIP4=129.148.174.27:SinstNM="atlantic": \
239 :sTERM="sun-cmd":BootSrvA=129.148.174.27:
240
241 Using lookup_dt, reexecute the lookup and verify
242 that the value portion of the record has been
243 modified correctly.
244
245 Case #10 delete_dt:
246
247 Using lookup_dt to find the record with a DT_QKEY of
248 "SUNW.Ultra-1", delete this record. Verify using lookup_dt that
249 this record can no longer be found (DSVC_NOENT).
250
251 Case #11 close_dt:
252
253 Close the open instance of the dhcptab container. Verify
254 that close_dt returns DSVC_SUCCESS.
255
256 Case #12 remove_dt:
257
258 Remove the dhcptab container. Verify that it no longer
259 exists using list.
260
261 dhcp network Container API
262 ==========================
263
264 Case #13 open_dn:
265
266 Using DSVC_CREATE | DSVC_READ | DSVC_WRITE, create a
267 dhcp network container (called <network address>). Preserve the
268 handle returned for later use in the following test cases. PASS
269 if DSVC_SUCCESS is returned, terminate the test otherwise.
270 Verify that the dhcp network container exists using list.
271
272 Case #14 add_dn:
273
274 14.1. Initialize container.
275
276 Using the handle returned in case #13, add the
277 dhcp network test records to the dhcp network container.
278 Verify that the dhcp network container exists by
279 calling list.
280
281 14.2. Attempt to add duplicate record.
282
283 Attempt to add the 172.21.0.254 client record
284 to the <network address> dhcp network container. PASS
285 if DSVC_EXISTS is returned.
286
287 Case #15 lookup_dn:
288
289 15.1. Verify case #14.
290
291 Using a "count" of -1 and a "query" value
292 initialized using DSVC_QINIT (Figure 5 of ARCH[1]),
293 verify that the contents of the <network address>
294 container match the test data. "records" should equal
295 the number of records added in case #14. Note that the
296 order of the records returned may not be the same as the
297 order in which they were added in case #14.
298
299 15.2. Verify <network address> dhcp network container
300 type.
301
302 15.2.1. Look for all records with a DN_QCIP of
303 <network address>+100. Verify that only one
304 record (with a cip of <network address>+100 is
305 returned.
306
307 15.2.2. Look for all records with a DN_QMACRO
308 value of "atlantic". Verify that all records
309 are returned ("records" == 3000). Note that the
310 records returned may not be in the same order in
311 which they were added as part of case #14.
312
313 Case #16 modify_dn:
314
315 16.1. Using lookup_dn to find the record with a DN_QCIP
316 of <network address>+10, change the lease field to
317 1/1/2000 and the flags field to MANUAL. Use lookup_dn to
318 verify that the original record has been changed.
319
320 16.2. Using lookup_dn to find the record with a
321 DN_QFLAGS of MANUAL. Change the dn_cid field to
322 01080020FFFFFF, dn_flags field to MANUAL+AUTOMATIC,
323 dn_sip field to 172.23.0.77, dn_lease field to -1,
324 dn_macro field to "happy", and the dn_comment field to
325 "This is a test". Use lookup_dn to verify that the
326 original record has been changed correctly.
327
328 Case #17 delete_dn:
329
330 Using lookup_dn to find the record with a DN_QCIP of
331 <network address>+101, delete this record. Verify using
332 lookup_dn that this record can no longer be found.
333
334 Case #18 close_dn:
335
336 Close the open instance of the dhcp network container
337 <network address>. Verify that close_dn returns DSVC_SUCCESS.
338
339 Case #19 remove_dn:
340
341 Remove the dhcp network container <network address>.
342 Verify that the container is in fact gone using list.
343
344 FULL TEST
345
346 Description
347
348 This suite verifies that the dhcptab and dhcp network
349 table API function calls respond correctly when presented with
350 incorrect data. It also validates the MT-safeness of the API.
351 The test suite should allow any number of concurrent threads or
352 test suite processes to be invoked. The data must remain
353 consistent as measured at certain points during the test in
354 order for the test to be considered to have passed successfully.
355
356 Test Data
357
358 Item Description Application
359 ==== =========== ===========
360 <location> Public module specific status, list,
361 path name to container open_dt,
362 directory (e.g. /var/dhcp remove_dt,
363 for 'files' data store). open_dn,
364 remove_dn
365
366 <Server IP> System under test's IP N/A
367 address.
368
369 dt records As follows: *_dt
370
371 SrootOpt s Vendor=SUNW.Ultra-1 SUNW.i86pc,1,ASCII,1,0
372 SrootIP4 s Vendor=SUNW.Ultra-1 SUNW.i86pc,2,IP,1,1
373 SrootNM s Vendor=SUNW.Ultra-1 SUNW.i86pc,3,ASCII,1,0
374 SrootPTH s Vendor=SUNW.Ultra-1 SUNW.i86pc,4,ASCII,1,0
375 SswapIP4 s Vendor=SUNW.Ultra-1 SUNW.i86pc,5,IP,1,1
376 SswapPTH s Vendor=SUNW.Ultra-1 SUNW.i86pc,6,ASCII,1,0
377 SbootFIL s Vendor=SUNW.Ultra-1 SUNW.i86pc,7,ASCII,1,0
378 Stz s Vendor=SUNW.Ultra-1 SUNW.i86pc,8,ASCII,1,0
379 SbootRS s Vendor=SUNW.Ultra-1 SUNW.i86pc,9,NUMBER,2,1
380 SinstIP4 s Vendor=SUNW.Ultra-1 SUNW.i86pc,10,IP,1,1
381 SinstNM s Vendor=SUNW.Ultra-1 SUNW.i86pc,11,ASCII,1,0
382 SinstPTH s Vendor=SUNW.Ultra-1 SUNW.i86pc,12,ASCII,1,0
383 SsysidCF s Vendor=SUNW.Ultra-1 SUNW.i86pc,13,ASCII,1,0
384 SjumpsCF s Vendor=SUNW.Ultra-1 SUNW.i86pc,14,ASCII,1,0
385 Sterm s Vendor=SUNW.Ultra-1 SUNW.i86pc,15,ASCII,1,0
386 Locale m :UTCoffst=-18000:
387 Solaris m :SrootIP4=129.148.174.27:SrootNM="atlantic": \
388 :SinstIP4=129.148.174.27:SinstNM="atlantic": \
389 :Sterm="xterm":BootSrvA=129.148.174.27:
390 sparc m \
391 :SrootPTH="/export/s28/solaris1of2.s28s_wos/latest/Solaris_8/Tools/Boot": \
392 :SinstPTH="/export/s28/solaris1of2.s28s_wos/latest":
393 sun4u m :Include=Solaris:Include=sparc:
394 i86pc m :Include=Solaris:SbootFIL="/platform/i86pc/kernel/unix": \
395 :SinstPTH="/export/s28/solaris1of2.s28x_wos/latest": \
396 :SrootPTH="/export/s28/solaris1of2.s28x_wos/latest/Solaris_8/Tools/Boot":
397 SUNW.i86pc m :Include=i86pc:
398 SUNW.Ultra-1 m :SbootFIL="/platform/sun4u/kernel/sparcv9/unix": \
399 :Include=sun4u:
400 172.21.0.0 m :Subnet=255.255.0.0:Router=172.21.0.2: \
401 :Broadcst=172.21.255.255:
402 atlantic m :Include=Locale:Timeserv=129.148.174.27:LeaseTim=3600: \
403 :LeaseNeg:Hostname:DNSdmain="snt.east.sun.com": \
404 :DNSserv=172.21.0.1:
405 010800207E8A02 m :Impress=172.22.255.27:
406
407
408 172.21.0.0 Dhcp network container. *_dn
409
410 dn records ~3000, as follows: *_dn
411
412 00 00 172.21.0.6 <Server IP> 0 atlantic
413 .
414 .
415 .
416 00 00 172.21.12.6 <Server IP> 0 atlantic
417
418 Case #1:
419 Disable the underlying data service. How this is done
420 is data service-dependent. Call each of status, version,
421 capability, list, open_dt, remove_dt, open_dn, and remove_dn.
422 PASS if the function returns DSVC_INTERNAL or
423 DSVC_MODULE_ERROR. What is returned is data service-specific. If
424 this test FAILs (e.g. a function returns DSVC_SUCCESS, terminate
425 the test run.
426
427 Cleanup: Reenable the underlying data service.
428
429 dhcptab Container API
430 =====================
431
432 Case #2 list_dt:
433
434 2.1. Invalid Location
435
436 Call function with an invalid <location>. PASS
437 if DSVC_INVAL is returned. If this case fails, abort
438 the test.
439
440 2.2. No container
441
442 Verify that list returns DSVC_NOENT.
443
444 Case #3 open_dt:
445
446 3.1. No container
447
448 Call function with DSVC_READ | DSVC_WRITE.
449 Verify that DSVC_NOENT is returned.
450
451 3.2. NON_BLOCK
452
453 Using DSVC_CREATE | DSVC_READ | DSVC_WRITE,
454 call open_dt to create a dhcptab container. Call
455 close_dt to close the handle. Call open_dt with
456 DSVC_READ | DSVC_WRITE | DSVC_NONBLOCK. Depending on
457 whether the public module supports it (see module doc),
458 the function should return either DSVC_SUCCESS or
459 DSVC_UNSUPPORTED. If NON_BLOCK access is supported,
460 endeavor to make the underlying service temporarily
461 unavailable (e.g: NIS+: checkpoint the database). Call
462 open_dt again with the same flags (read, write,
463 nonblock). open_dt must fail and return DSVC_BUSY.
464
465 Cleanup: re-enable underlying service, close the open
466 handle.
467
468 3.3. Container exists
469
470 Call function with DSVC_CREATE | DSVC_READ |
471 DSVC_WRITE. Verify that the function returns
472 DSVC_EXISTS.
473
474 Cleanup: remove the dhcptab container using remove_dt.
475
476 Case #4 add_dt:
477
478 Create and load the dhcptab as per Case #6 and Case #7.1
479 of the Basic Sanity Test.
480
481 4.1. Record exists
482
483 Attempt to add a test dhcptab record to the
484 dhcptab. Verify that DSVC_EXISTS is returned.
485
486 4.2. Busy
487
488 Close open handle with close_dt. Reopen with
489 DSVC_NONBLOCK specified. If nonblocking semantics are
490 supported, then make the data service busy through the
491 use of a data service-specific technique and attempt to
492 add an additional dhcptab record. Verify that DSVC_BUSY
493 is returned. Remove the data service busy condition and
494 reattempt the add operation. Verify that DSVC_SUCCESS is
495 returned. close_dt the container.
496
497 4.3. Read only
498
499 Close any open handles. Reopen the dhcptab with
500 DSVC_READ access only. If success is returned, attempt
501 to add a new record to the dhcptab. Verify that
502 DSVC_ACCESS is returned. close_dt the handle. Note that
503 some data store modules may return DSVC_UNSUPPORTED for
504 read-only access.
505
506 Cleanup: Close open handles, remove the dhcptab using
507 remove_dt.
508
509 Case #5 lookup_dt:
510
511 Create and load the dhcptab as per Case #6 and Case #7.1
512 of the Basic Sanity Test.
513
514 5.1. Record does not exist.
515
516 Produce a dhcptab container query that would not
517 be satisfied by the test data. Verify that DSVC_SUCCESS
518 is returned, and "records" is 0.
519
520 5.2. Busy
521
522 Close dhcptab handle with close_dt. Reopen with
523 DSVC_NONBLOCK specified. IF DSVC_SUCCESS is returned
524 (Nonblocking access is supported), using a data
525 service-specific technique for making the service busy,
526 attempt to perform a valid lookup of a dhcptab record.
527 Verify that DSVC_BUSY is returned. Remove the busy
528 condition, and reattempt the lookup. Verify that
529 DSVC_SUCCESS is returned, and that the data returned is
530 valid. close_dt the handle.
531
532 5.3. Write only
533
534 Reopen the dhcptab container with DSVC_WRITE
535 access only. If success is returned, attempt to perform
536 lookup_dt's using any syntactically legal query for the
537 dhcptab. Verify that DSVC_ACCESS is returned. close_dt
538 the handle.
539
540 5.4. Multiple matching records
541
542 Reopen the dhcptab container as per case
543 #6 and case #7.1 of the Basic Sanity Test. Using
544 modify_dt, change the dt_key for the SrootOpt symbol
545 such that the key value is now sun4u. Form a query which
546 simply specifies a DT_QKEY value of "sun4u". Verify that
547 exactly two records are returned, and that there values
548 are what is expected (one a macro, the other a symbol,
549 with the appropriate values).
550
551 Cleanup: Remove the dhcptab container using remove_dt.
552
553 Case #6 modify_dt:
554
555 Create and load the dhcptab container as per Case #6
556 and Case #7.1 of the Basic Sanity Test.
557
558 6.1. Unknown record
559
560 Fabricate dt_rec_t elements initialized with
561 data known not to exist in the dhcptab. Attempt to
562 modify these elements. Verify that DSVC_NOENT is
563 returned.
564
565 6.2. Update Collision #1
566
567 Use lookup_dt to find a valid dhcptab record.
568 Change the signature on the resultant dt_rec_t. Attempt
569 to modify the record. Verify that DSVC_COLLISION is
570 returned.
571
572 6.3. Update Collision #2
573
574 Use lookup_dt to find a valid dhcptab record.
575 Attempt to rename the record to one that already exists
576 (dt_key + dt_type). Verify that DSVC_EXISTS is returned.
577
578 6.4. Busy
579
580 Close the dhcptab with close_dt. Reopen with
581 DSVC_NONBLOCK specified. If DSVC_SUCCESS is returned (it
582 is supported), acquire a valid dhcptab record using
583 lookup_dt. Using a data service specific technique for
584 making the service busy, attempt to modify the value
585 (non-key fields) of the record. Verify that DSVC_BUSY is
586 returned. Remove the busy condition, and reattempt the
587 modify. Verify that DSVC_SUCCESS is returned.
588 Reacquire the record. Verify that the contents have been
589 suitably updated. close_dt the container.
590
591 6.5. Read only
592
593 Reopen the dhcptab with DSVC_READ access only.
594 If success is returned, locate a valid container record
595 using the appropriate query to lookup_dt. Modify the
596 contents of the record. Attempt to commit the modify to
597 the dhcptab. Verify that DSVC_ACCESS is returned.
598 close_dt the dhcptab handle.
599
600 Cleanup: Remove the dhcptab using remove_dt.
601
602 Case #7 free_dtrec_list:
603
604 This function should be used to release the results of
605 lookup_dt calls. Its operation must be validated by running this
606 test under bcheck with -memuse, and ensuring that no free blocks
607 remain after exit. Note that the test must be written with care
608 to make this case useful (free any allocated memory when it is
609 no longer needed).
610
611 Case #8 delete_dt:
612
613 Create and load the dhcptab container as per Case #6 and
614 Case #7.1 of the Basic Sanity Test.
615
616 8.1 Unknown record
617
618 Fabricate dt_rec_t containing a record known
619 not to exist in the dhcptab. Attempt to delete the
620 record. Verify that DSVC_NOENT is returned.
621
622 8.2 Busy
623
624 Close the dhcptab with close_dt. Reopen with
625 DSVC_NONBLOCK specified. If DSVC_SUCCESS is returned,
626 acquire a valid dhcptab container record using
627 lookup_dt. Using a data service specific technique for
628 making the service busy, attempt to delete the record.
629 Verify that DSVC_BUSY is returned. Remove the busy
630 condition, and reattempt the delete. Verify that
631 DSVC_SUCCESS is returned. Attempt to reacquire the
632 record. Verify that the record has in fact been deleted.
633 Close the dhcptab using close_dt.
634
635 8.3 Read only
636
637 Reopen the dhcptab container with DSVC_READ
638 access only. If success is returned, locate a valid
639 dhcptab record using an appropriate query to lookup_dt.
640 Attempt to delete the record. Verify that DSVC_ACCESS is
641 returned. Close the dhcptab using close_dt.
642
643 Cleanup: Remove the dhcptab using remove_dt.
644
645 Case #9 close_dt:
646
647 Verify that this function handles nonblocking semantics
648 correctly. Create a dhcptab as per case #6 of the Basic Sanity
649 Test, with the exception that DSVC_NONBLOCK is specified. If
650 nonblocking mode is supported, then using a data service
651 specific technique for making the service busy, attempt to close
652 the dhcptab handle returned by open_dt. Verify that DSVC_BUSY
653 is returned. Remove the busy condition, and reattempt the
654 close_dt. Verify that DSVC_SUCCESS is returned.
655
656 Cleanup: Remove the dhcptab container using remove_dt.
657
658 Case #10 remove_dt:
659
660 Verify that this function handles nonblocking semantics
661 correctly. Create a dhcptab container as per Case #6 of the Basic
662 Sanity Test. Close open handle using close_dt. Reopen with
663 DSVC_NONBLOCK specified. If nonblocking mode is supported, using
664 a data service specific technique for making the service busy,
665 attempt to remove the dhcptab container. Verify that DSVC_BUSY is
666 returned. Remove the busy condition, and reattempt the remove.
667 Verify that the dhcptab container is removed using list and that
668 the function returns DSVC_SUCCESS.
669
670 Cleanup: Close the open handle using close_dt (ignore result).
671
672 dhcp network Container API
673 ==========================
674
675 Case #11 list_dn:
676
677 11.1. Invalid Location
678
679 Call function with an invalid <location>. PASS
680 if DSVC_INVAL is returned. If this case fails, abort
681 the test.
682
683 11.2. No container
684
685 Verify that list returns DSVC_NOENT.
686
687 Case #12 open_dn:
688
689 12.1. No container
690
691 Call function with DSVC_READ | DSVC_WRITE and
692 <network address>. Verify that DSVC_NOENT is returned.
693
694 12.2. NON_BLOCK
695
696 Using the flag values of DSVC_CREATE |
697 DSVC_READ | DSVC_WRITE | DSVC_NONBLOCK, the function
698 to create a dhcp network container called <network
699 address>. Depending on whether the public module
700 supports nonblocking semantics (see module doc),
701 the function should return either DSVC_SUCCESS or
702 DSVC_UNSUPPORTED. If NON_BLOCK access is supported,
703 endeavor to make the underlying service temporarily
704 unavailable (e.g: NIS+: checkpoint the database). Call
705 open_dn again with the same flags (read, write,
706 nonblock). open_dn must fail and return DSVC_BUSY.
707
708 Cleanup: re-enable underlying service, close the open
709 handle.
710
711 12.3. Container exists.
712
713 Using the flag values DSVC_CREATE | DSVC_READ |
714 DSVC_WRITE, attempt to open <network address>. Verify
715 that the function returns DSVC_EXISTS.
716
717 Cleanup: Remove the <network address> dhcp network
718 container using remove_dn.
719
720 Case #13 add_dn:
721
722 Create and load the <network address> dhcp network
723 container as per Case #13 and Case #14.1 of the Basic Sanity
724 Test.
725
726 13.1. Record exists
727
728 Attempt to add a test dhcp network record to
729 the <network address> dhcp network container. Verify
730 that DSVC_EXISTS is returned.
731
732 13.2. Busy
733
734 Close open handle with close_dn. Reopen with
735 DSVC_NONBLOCK specified. If nonblocking semantics are
736 supported, then make the data service busy through the
737 use of a data service-specific technique and attempt to
738 add an additional dhcp network record. Verify that
739 DSVC_BUSY is returned. Remove the data service busy
740 condition and reattempt the add operation. Verify that
741 DSVC_SUCCESS is returned. close_dn the container.
742
743 13.3. Read only
744
745 Close any open handles. Reopen the <network
746 address> dhcp network container with DSVC_READ access
747 only. If success is returned, attempt to add a new
748 record to the dhcp network container. Verify that
749 DSVC_ACCESS is returned. close_dn the handle. Note that
750 some data store modules may return DSVC_UNSUPPORTED for
751 read-only access.
752
753 Cleanup: Close open handles, remove the <network
754 address> dhcp network container using remove_dn.
755
756 Case #14 lookup_dn:
757
758 Create and load the <network address> dhcp network
759 container as per Case #13 and Case #14.1 of the Basic Sanity
760 Test.
761
762 14.1. Record does not exist.
763
764 Produce a dhcp network container query that
765 would not be satisfied by the test data. Verify that
766 DSVC_SUCCESS is returned, and "records" is 0.
767
768 14.2. Busy
769
770 Close the <network address> dhcp network handle
771 with close_dn. Reopen with DSVC_NONBLOCK specified. If
772 DSVC_SUCCESS is returned (Nonblocking access is
773 supported), using a data service-specific technique for
774 making the service busy, attempt to perform a valid
775 lookup of a dhcp network record. Verify that DSVC_BUSY
776 is returned. Remove the busy condition, and reattempt
777 the lookup. Verify that DSVC_SUCCESS is returned, and
778 that the data returned is valid. close_dn the handle.
779
780 14.3. Write only
781
782 Reopen the dhcp network container with DSVC_WRITE
783 access only. If success is returned, attempt to perform
784 lookup_dn's using any syntactically legal query for the
785 <network address> dhcp network container. Verify that
786 DSVC_ACCESS is returned. close_dn the handle.
787
788 14.4. Multiple matching records
789
790 Reopen the dhcp network container as per case
791 #13 and case #14.1 of the Basic Sanity Test. Using
792 modify_dn, change the dn_cid fields for records <network
793 address>+1 through <network address>+217 to 01BADDCAFE.
794 Form a query which simply specifies a DN_QCID of
795 01BADDCAFE. Confirm that exactly 216 records are
796 returned, and that their CIP range is correct.
797
798 Cleanup: Remove the <network address> dhcp network
799 container using remove_dn.
800
801 Case #15 modify_dn:
802
803 Create and load the <network address> dhcp network
804 container as per Case #13 and Case #14.1 of the Basic Sanity
805 Test.
806
807 15.1. Unknown record
808
809 Fabricate dn_rec_t elements initialized with
810 data known not to exist in the dhcp network container.
811 Attempt to modify these elements. Verify that DSVC_NOENT
812 is returned.
813
814 15.2. Update Collision #1
815
816 Use lookup_dn to find a valid dhcp network record.
817 Change the signature on the resultant dn_rec_t. Attempt
818 to modify the record. Verify that DSVC_COLLISION is
819 returned.
820
821 15.3. Update Collision #2
822
823 Use lookup_dn to find a valid dhcp network record.
824 Attempt to rename the record to one that already exists
825 (dn_cid, dn_flags, dn_cip, dn_sip, dn_lease, dn_macro).
826 Verify that DSVC_EXISTS is returned.
827
828 15.4. Busy
829
830 Close the dhcp network container with close_dn.
831 Reopen with DSVC_NONBLOCK specified. If DSVC_SUCCESS is
832 returned (nonblocking semantics are supported), acquire
833 a valid dhcp network record using lookup_dn. Using a
834 data service specific technique for making the service
835 busy, attempt to modify the value (non-key fields) of
836 the record. Verify that DSVC_BUSY is returned. Remove
837 the busy condition, and reattempt the modify. Verify
838 that DSVC_SUCCESS is returned. Reacquire the record.
839 Verify that the contents have been suitably updated.
840 close_dn the container.
841
842 15.5. Read only
843
844 Reopen the dhcp network container with DSVC_READ
845 access only. If success is returned, locate a valid
846 container record using the appropriate query to
847 lookup_dn. Modify the contents of the record. Attempt
848 to commit the modify to the dhcp network container.
849 Verify that DSVC_ACCESS is returned. close_dn the
850 dhcp network container handle.
851
852 Cleanup: Remove the dhcp network container using
853 remove_dn.
854
855 Case #16 free_dnrec_list:
856
857 This function should be used to release the results of
858 lookup_dn calls. Its operation must be validated by running this
859 test under bcheck with -memuse, and ensuring that no free blocks
860 remain after exit. Note that the test must be written with care
861 to make this case useful (free any allocated memory when it is
862 no longer needed).
863
864 Case #17 delete_dn:
865
866 Create and load the <network address> dhcp network
867 container as per Case #13 and Case #14.1 of the Basic Sanity
868 Test.
869
870 17.1 Unknown record
871
872 Fabricate dn_rec_t containing a record known
873 not to exist in the dhcp network container. Attempt
874 to delete the record. Verify that DSVC_NOENT is returned.
875
876 17.2 Busy
877
878 Close the dhcp network container with close_dn.
879 Reopen with DSVC_NONBLOCK specified. If DSVC_SUCCESS is
880 returned, acquire a valid dhcp network container record
881 using lookup_dn. Using a data service specific technique
882 for making the service busy, attempt to delete the record.
883 Verify that DSVC_BUSY is returned. Remove the busy
884 condition, and reattempt the delete. Verify that
885 DSVC_SUCCESS is returned. Attempt to reacquire the
886 record. Verify that the record has in fact been deleted.
887 Close the dhcp network container using close_dn.
888
889 17.3 Read only
890
891 Reopen the dhcp network container with DSVC_READ
892 access only. If success is returned, locate a valid
893 dhcp network record using an appropriate query to
894 lookup_dn. Attempt to delete the record. Verify that
895 DSVC_ACCESS is returned. Close the dhcp network
896 container using close_dn.
897
898 Cleanup: Remove the dhcp network container using
899 remove_dn.
900
901 Case #18 close_dn:
902
903 Verify that this function handles nonblocking semantics
904 correctly. Create the <network address> dhcp network container
905 as per case #13 of the Basic Sanity Test, with the exception
906 that DSVC_NONBLOCK is specified. If nonblocking mode is
907 supported, then using a data service specific technique for
908 making the service busy, attempt to close the dhcp network
909 handle returned by open_dn. Verify that DSVC_BUSY is returned.
910 Remove the busy condition, and reattempt the close_dn. Verify
911 that DSVC_SUCCESS is returned.
912
913 Cleanup: Remove the dhcp network container using remove_dn.
914
915 Case #19 remove_dn:
916
917 Verify that this function handles nonblocking semantics
918 correctly. Create the <network address> dhcp network container
919 as per Case #13 of the Basic Sanity Test, with the exception
920 that DSVC_NONBLOCK is specified. If nonblocking mode is
921 supported, using a data service specific technique for making
922 the service busy, attempt to remove the dhcp network container.
923 Verify that DSVC_BUSY is returned. Remove the busy condition,
924 and reattempt the remove. Verify that the <network address> dhcp
925 network container is removed using list and that the function
926 returns DSVC_SUCCESS.
927
928 Cleanup: Close the open handle using close_dn (ignore result).
929
930 Case #20 Multi-access stress
931
932 Public layer modules are not required to manage reference
933 counts for open instances. So while individual handles are
934 considered to be MT-safe (and parallel access to containers is
935 suitably protected), an application using the service provider
936 layer API must synchronize close and/or container remove
937 operations among threads such that no threads hold handles to a
938 container after the handle has been closed or the container has
939 been removed.
940
941 This case assumes a test which is multi-threaded, and
942 can run the following test using from 1 to THREADS threads. The
943 test can also be run in multiple concurrent processes.
944
945 The goal of this test is to ensure that the API is
946 MT-safe with respect to the containers and the records contained
947 within those containers. This goal is accomplished by verifying
948 that the end result of the test is consistent.
949
950 Tunable default values:
951
952 PROCESSES: 20
953 THREADS: 20
954
955 20.1 The dhcptab container test
956
957 20.1.1 open_dt
958
959 Create a dhcptab using DSVC_CREATE |
960 DSVC_READ | DSVC_WRITE. If DSVC_EXISTS is
961 returned, retry the open attempt w/o the
962 DSVC_CREATE flag. Log that this event occurred.
963 Handle will be used for balance of test. If any
964 other error occurs, terminate the test as
965 failed.
966
967 20.1.2 add_dt
968
969 Add the test data records to the dhcptab
970 container. If DSVC_EXISTS is returned, skip that
971 record, and continue attempting to add the other
972 records. Log that this event occurred. If any
973 other error occurs, terminate the test as
974 failed.
975
976 20.1.3 lookup_dt
977
978 Using DT_QKEY of "atlantic" and DT_QTYPE
979 of "m", find the atlantic record. Compare its
980 value against the test data. If it has
981 changed, then output a message to this affect.
982 If any error occurs, terminate the test as failed.
983
984 20.1.4 modify_dt
985
986 Using the results of 20.1.3, change the
987 record as follows. If it is no different from
988 the test data, change the value to:
989
990 :Timeserv=129.148.174.28:LeaseTim=86400: \
991 :Hostname:DNSdmain="east.sun.com":DNSserv=172.23.3.3:
992
993 If it doesn't match the test data
994 value, change the LeaseTim by incrementing it by
995 one. Attempt to update the record. If it fails
996 with DSVC_COLLISION, retry 20.1.3 and 20.1.4 for
997 three attempts. Log message if modify was
998 unsuccessful. If any other error occurs,
999 terminate the test as failed.
1000
1001 20.1.5 delete_dt
1002
1003 Use lookup_dt to find a DT_QKEY of
1004 "SjumpsCF" and a DT_QTYPE of "s". If it does
1005 not exist, log a message. If it does exist,
1006 attempt to delete it. If DSVC_NOENT is returned,
1007 log a message.
1008
1009 20.1.6 close_dt
1010
1011 Use close_dt to close the open handle.
1012 If DSVC_NOENT is returned, log a message.
1013
1014 20.1.7 epilogue
1015
1016 Compare the resultant dhcptab container
1017 to the test data. The only differences should be
1018 a changed value of the atlantic macro as
1019 expected from 20.1.4 and the SjumpsCF symbol
1020 should be removed. Any other inconsistency means
1021 the test has failed.
1022
1023 Clean up: Remove the dhcptab container.
1024
1025 20.2 The dhcp network table container test
1026
1027 20.2.1 open_dn
1028
1029 Create a <network address> dhcp network
1030 table using DSVC_CREATE | DSVC_READ | DSVC_WRITE.
1031 If DSVC_EXISTS is returned, retry the open
1032 attempt w/o the DSVC_CREATE flag. Log that this
1033 event occurred. Handle will be used for balance
1034 of test. If any other error occurs, terminate
1035 the test as failed.
1036
1037 20.2.2 add_dn
1038
1039 Add the test data records to the dhcp
1040 network table container. If DSVC_EXISTS is
1041 returned, skip that record, and continue
1042 attempting to add the other records. Log that
1043 this event occurred. If any other error occurs,
1044 terminate the test as failed.
1045
1046 20.2.3 lookup_dn
1047
1048 Find the DN_QCIP of <network address>+102
1049 record. Compare its value against the test data.
1050 If it has changed, then output a message to this
1051 affect. If any error occurs, terminate the test
1052 as failed.
1053
1054 20.2.4 modify_dn
1055
1056 Using the results of 20.2.3, change the
1057 record as follows. If it is no different from
1058 the test data, change the value to:
1059
1060 01DEADBEEF 03 <network address>+102 172.23.3.3 941619403 Solaris
1061
1062 If it doesn't match the test data
1063 value, change dn_lease by incrementing it by
1064 one. Attempt to update the record. If it fails
1065 with DSVC_COLLISION, retry 20.2.3 and 20.2.4 for
1066 three attempts. Log message if modify was
1067 unsuccessful. If any other error occurs,
1068 terminate the test as failed.
1069
1070 20.2.5 delete_dn
1071
1072 Use lookup_dn to find a DN_QCIP of
1073 <network address>+1001. If it does not exist,
1074 log a message. If it does exist, attempt to
1075 delete it. If DSVC_NOENT is returned, log a
1076 message.
1077
1078 20.2.6 close_dn
1079
1080 Use close_dn to close the open handle.
1081 If DSVC_NOENT is returned, log a message.
1082
1083 20.2.7 epilogue
1084
1085 The <network address> dhcp network
1086 container should be consistent at the end of
1087 a test run. The only differences should be a
1088 changed value of the <network address>+102
1089 record with the value as per 20.2.4 and the
1090 lease time potentially incremented, as well as
1091 the <network address>+1001 record missing.
1092 Any other inconsistency means the test has
1093 failed.
1094
1095 Cleanup: remove <network address> dhcp network
1096 container.
1097
1098 20.3 Multi-process run
1099
1100 Run 20.1 and 20.2 in PROCESSES separate
1101 processes.
1102
1103 20.4 Multi-threaded run, single process
1104
1105 Run 20.1 and 20.2 in THREADS separate threads
1106 within a single process.
1107
1108 20.5 Multi-process, Multi-threaded run
1109
1110 Run 20.1 and 20.2 in PROCESSES separate
1111 processes each spawning THREADS separate threads.
1112
1113 Case #21 Capacity
1114
1115 This test case endeavors to probe the stability and the
1116 performance of the public module implementation when:
1117
1118 a) The data storage containers are filled to capacity.
1119
1120 b) The data storage containers are overfilled.
1121
1122 Note that while the number of records within a dhcptab
1123 container could be infinite, the number of records within a dhcp
1124 network container is bounded by the number of possible IP
1125 addresses within the network represented by the container. If a
1126 class A network is represented, there can be up to 16,777,215
1127 possible records. The total number of records supported by a
1128 public module (with some overhead for container information) is
1129 the upper bound. That total number could be influenced by
1130 settings in the underlying hosting data service, or by the
1131 available memory or disk resources of the machine under test.
1132 Since record sizes for dhcptab and dhcp network containers
1133 differ, discovering the maximum number of possible records
1134 requires some dynamic experimentation by the test itself.
1135
1136 21.1 Initialization
1137
1138 Call capability. The max number of possible
1139 records for the environment under test will be contained
1140 within the returned structure as will some estimate of
1141 the operations per second claimed by the public module
1142 in the run environment. A dhcptab will be created with
1143 contains 1/3 of the maximum number of records. One or
1144 more dhcp network containers will be created to contain
1145 the balance of the records. A multithreaded program can
1146 create the containers and load them with single threads,
1147 one for each container. A consistent series of records
1148 must be added to the dhcptab (monotonically increasing
1149 symbol / macro records created, each with unique value
1150 portions which could be calculated by the key fields of
1151 the record). dhcp network container records simply contain
1152 records unique by client IP address.
1153
1154 Initialization will stop when no more records can be
1155 added to the system (XXX - what sort of error code would
1156 be returned? DSVC_INTERNAL?). Operations per second
1157 must be measured during the initialization process to
1158 determine whether it is close to the advertised number
1159 (XXX - how could this be verified?).
1160
1161 21.2 Modify
1162
1163 For every existing dhcp network record, modify
1164 the lease time such that it is set to the number of
1165 modify operations done during this subcase (first one ==
1166 1, last 1+N). Measure operations per second during this
1167 process.
1168
1169 21.3 Add
1170
1171 Attempt to add a new dhcptab and a new dhcp
1172 network container(s) record. This operation should fail
1173 (XXX expected results?).
1174
1175 21.4 Lookup
1176
1177 Form a configured number of legal queries (TBD
1178 tunable) for the dhcptab and dhcp network container(s).
1179 Validate that the data returned is what is expected
1180 based upon knowledge of relationship between the record
1181 being searched for and the expected value based upon the
1182 search parameters. PASS if queries are successful.
1183 Measure operations per second during this process for
1184 comparison against advertised number.
1185
1186 21.5 Delete
1187
1188 Using lookup and delete, find and delete every
1189 single record added by the test. Confirm that the
1190 containers contain no records. Measure operations per
1191 second during this process for comparison against the
1192 advertised number.
1193
1194 Cleanup: Remove the containers.
1195
1196 REFERENCES
1197
1198 [1] "Enterprise DHCP Service Architecture Specification", mwc,
1199 6/25/1999.
1200
1201 [2] "Enterprise Reference Hardware Platforms", mwc, 10/23/1999.