OpenSolaris_b135/lib/libdhcpsvc/tests/specs/public.txt
#ident "%Z%%M% %I% %E% SMI" mwc
CDDL HEADER START
The contents of this file are subject to the terms of the
Common Development and Distribution License, Version 1.0 only
(the "License"). You may not use this file except in compliance
with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
or http://www.opensolaris.org/os/licensing.
See the License for the specific language governing permissions
and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each
file and include the License file at usr/src/OPENSOLARIS.LICENSE.
If applicable, add the following below this CDDL HEADER, with the
fields enclosed by brackets "[]" replaced with your own identifying
information: Portions Copyright [yyyy] [name of copyright owner]
CDDL HEADER END
Enterprise: Public Layer Test Specification
===========================================
ABSTRACT
This document describes a test specification intended to be used
in the development of tests designed to validate the service provider
layer API described in Section 2.2 of the Enterprise DHCP Service
Architecture Specification (ARCH) [1]. The first test is a basic sanity
test, designed to verify that the API works as designed when fed data
in the correct form. The second test is a full test, which compliments
the basic sanity test by providing cases which test the stability and
MT-safeness of the API.
TEST APPLICATION
Test suite(s) written to this specification should be run on
every available public module on the reference platform of each of the
supported architectures (sparcv8, sparcv9, IA32, IA64) for each build
of the ON consolidation. See "Enterprise Reference platforms" [2] for
more information.
TEST PREPARATION
The packages SUNWdhc{df,db,dn} containing the public module(s)
under test need to be installed in /usr/lib/inet/dhcp/svc on the machine
under test. The data service(s) (if necessary) which hosts the data
store must be configured and running. A data store container directory
(location) within the data service must exist and be empty. The machine
under test must have the appropriate authorization (root user) for
accessing the hosting data service. Note that it is important to note
whether the data service is hosted on the test machine, or whether the
data service is hosted on a different machine and the machine under
test is a client of that data service. Where the data service is hosted
will have an affect on the test results, particularly performance.
BASIC SANITY TEST
Description
This test validates the basic operation of service
provider layer API function calls when presented with valid
arguments in a valid run environment. It is implemented as a
multithreaded program running a single thread to exercise the API
referenced in Section 2.2 of ARCH [1]. This program should create
dhcptab and dhcp network containers within the data store, and
exercise the *_dt and *_dn calls to add, modify, and delete
multiple records. The result of the add, modify, and delete
operations must be validated between each operation. The program
should be written such that the initial condition described under
TEST PREPARATION is restored. Operations are PASS/FAIL, and must
be compared against a human-verified expect file.
Test Data
Item Description Application
==== =========== ===========
<location> Public module specific status, list,
path name to container open_dt,
directory (e.g. /var/dhcp remove_dt,
for 'files' data store). open_dn,
remove_dn
<Server IP> System under test's IP N/A
address.
dt records As follows: *_dt
SrootOpt s Vendor=SUNW.Ultra-1 SUNW.i86pc,1,ASCII,1,0
SrootIP4 s Vendor=SUNW.Ultra-1 SUNW.i86pc,2,IP,1,1
SrootNM s Vendor=SUNW.Ultra-1 SUNW.i86pc,3,ASCII,1,0
SrootPTH s Vendor=SUNW.Ultra-1 SUNW.i86pc,4,ASCII,1,0
SswapIP4 s Vendor=SUNW.Ultra-1 SUNW.i86pc,5,IP,1,1
SswapPTH s Vendor=SUNW.Ultra-1 SUNW.i86pc,6,ASCII,1,0
SbootFIL s Vendor=SUNW.Ultra-1 SUNW.i86pc,7,ASCII,1,0
Stz s Vendor=SUNW.Ultra-1 SUNW.i86pc,8,ASCII,1,0
SbootRS s Vendor=SUNW.Ultra-1 SUNW.i86pc,9,NUMBER,2,1
SinstIP4 s Vendor=SUNW.Ultra-1 SUNW.i86pc,10,IP,1,1
SinstNM s Vendor=SUNW.Ultra-1 SUNW.i86pc,11,ASCII,1,0
SinstPTH s Vendor=SUNW.Ultra-1 SUNW.i86pc,12,ASCII,1,0
SsysidCF s Vendor=SUNW.Ultra-1 SUNW.i86pc,13,ASCII,1,0
SjumpsCF s Vendor=SUNW.Ultra-1 SUNW.i86pc,14,ASCII,1,0
Sterm s Vendor=SUNW.Ultra-1 SUNW.i86pc,15,ASCII,1,0
Locale m :UTCoffst=-18000:
Solaris m :SrootIP4=129.148.174.27:SrootNM="atlantic": \
:SinstIP4=129.148.174.27:SinstNM="atlantic": \
:Sterm="xterm":BootSrvA=129.148.174.27:
sparc m \
:SrootPTH="/export/s28/solaris1of2.s28s_wos/latest/Solaris_8/Tools/Boot": \
:SinstPTH="/export/s28/solaris1of2.s28s_wos/latest":
sun4u m :Include=Solaris:Include=sparc:
i86pc m :Include=Solaris:SbootFIL="/platform/i86pc/kernel/unix": \
:SinstPTH="/export/s28/solaris1of2.s28x_wos/latest": \
:SrootPTH="/export/s28/solaris1of2.s28x_wos/latest/Solaris_8/Tools/Boot":
SUNW.i86pc m :Include=i86pc:
SUNW.Ultra-1 m :SbootFIL="/platform/sun4u/kernel/sparcv9/unix": \
:Include=sun4u:
172.21.0.0 m :Subnet=255.255.0.0:Router=172.21.0.2: \
:Broadcst=172.21.255.255:
atlantic m :Include=Locale:Timeserv=129.148.174.27:LeaseTim=3600: \
:LeaseNeg:Hostname:DNSdmain="snt.east.sun.com": \
:DNSserv=172.21.0.1:
010800207E8A02 m :Impress=172.22.255.27:
172.21.0.0 Dhcp network container. *_dn
dn records ~3000, as follows: *_dn
00 00 172.21.0.6 <Server IP> 0 atlantic
.
.
.
00 00 172.21.12.6 <Server IP> 0 atlantic
Generic Data Store Status
=========================
Case #1 status:
Call function with <location>. PASS if DSVC_SUCCESS is
returned, FAIL otherwise. If this case fails, abort the test.
Case #2 version:
Call function. Version value returned must be one (1)
for PASS. If this case fails, abort the test.
Case #3 capability:
Call function. Compare returned capability against
confirmed capability known for the public module under test.
Match is PASS.
Case #4 list:
Call function with <location>. PASS if DSVC_NOENT is
returned, listppp is NULL, and count is set to 0. As part of
Test preparation, there should be *no* containers of any kind in
the underlying data service of the public module. If this case
fails, abort the test.
dhcptab Container API
=====================
Case #5 alloc_dtrec:
Call function, verify that a non-NULL dt_rec_t pointer
is returned. Free result with free_dtrec.
Case #6 open_dt:
Create a dhcptab at <location> specifying DSVC_CREATE |
DSVC_READ | DSVC_WRITE. Preserve handpp for use in the following
cases. PASS if DSVC_SUCCESS is returned, abort the test
otherwise.
Case #7 add_dt:
7.1. Initialize container.
Using the handle returned in case #6, add the
dhcptab test records to the dhcptab. Verify that the
dhcptab exists by calling list.
7.2. Attempt to add duplicate record.
Attempt to add the SbootRS symbol definition and
172.21.0.0 macro definition to the dhcptab container.
PASS if DSVC_EXISTS is returned in both cases.
Case #8 lookup_dt:
8.1. Verify case #7.
Using a count value of -1 and a "query" value
initialized by DSVC_QINIT (Figure 5 of ARCH[1]), verify
that the contents of the dhcptab container match the
test data. Note that the order of the records returned
may not be the same as the order in which they were
added in case #7.
8.2 Verify dhcptab container type.
8.2.1. Look for all records with a DT_QTYPE
value of "s". Verify that only the "s" type
records are returned.
8.2.2. Look for all records with a DT_QTYPE
value of "m". Verify that only the "m" type
records are returned.
8.2.3. Look for DT_QKEY of "atlantic". Verify
that only the macro "atlantic" is returned, and
the value is correct.
8.2.4. Look for DTQKEY of i86pc and not a
DT_QTYPE of "m". Verify that only the macro
"i86pc" is returned.
Case #9 modify_dt:
9.1 Modify dhcptab container records
9.1.1. Using lookup_dt to find the record with a
DT_QKEY of "Sterm", change the name of the
record from "Sterm" to "sTERM". Use lookup_dt to
verify that the original record has been
renamed.
9.1.2. Using lookup_dt to find the record with a
DT_QKEY of "Solaris", change the value portion
of the record to be:
:SrootIP4=129.148.174.27:SrootNM="atlantic": \
:SinstIP4=129.148.174.27:SinstNM="atlantic": \
:sTERM="sun-cmd":BootSrvA=129.148.174.27:
Using lookup_dt, reexecute the lookup and verify
that the value portion of the record has been
modified correctly.
Case #10 delete_dt:
Using lookup_dt to find the record with a DT_QKEY of
"SUNW.Ultra-1", delete this record. Verify using lookup_dt that
this record can no longer be found (DSVC_NOENT).
Case #11 close_dt:
Close the open instance of the dhcptab container. Verify
that close_dt returns DSVC_SUCCESS.
Case #12 remove_dt:
Remove the dhcptab container. Verify that it no longer
exists using list.
dhcp network Container API
==========================
Case #13 open_dn:
Using DSVC_CREATE | DSVC_READ | DSVC_WRITE, create a
dhcp network container (called <network address>). Preserve the
handle returned for later use in the following test cases. PASS
if DSVC_SUCCESS is returned, terminate the test otherwise.
Verify that the dhcp network container exists using list.
Case #14 add_dn:
14.1. Initialize container.
Using the handle returned in case #13, add the
dhcp network test records to the dhcp network container.
Verify that the dhcp network container exists by
calling list.
14.2. Attempt to add duplicate record.
Attempt to add the 172.21.0.254 client record
to the <network address> dhcp network container. PASS
if DSVC_EXISTS is returned.
Case #15 lookup_dn:
15.1. Verify case #14.
Using a "count" of -1 and a "query" value
initialized using DSVC_QINIT (Figure 5 of ARCH[1]),
verify that the contents of the <network address>
container match the test data. "records" should equal
the number of records added in case #14. Note that the
order of the records returned may not be the same as the
order in which they were added in case #14.
15.2. Verify <network address> dhcp network container
type.
15.2.1. Look for all records with a DN_QCIP of
<network address>+100. Verify that only one
record (with a cip of <network address>+100 is
returned.
15.2.2. Look for all records with a DN_QMACRO
value of "atlantic". Verify that all records
are returned ("records" == 3000). Note that the
records returned may not be in the same order in
which they were added as part of case #14.
Case #16 modify_dn:
16.1. Using lookup_dn to find the record with a DN_QCIP
of <network address>+10, change the lease field to
1/1/2000 and the flags field to MANUAL. Use lookup_dn to
verify that the original record has been changed.
16.2. Using lookup_dn to find the record with a
DN_QFLAGS of MANUAL. Change the dn_cid field to
01080020FFFFFF, dn_flags field to MANUAL+AUTOMATIC,
dn_sip field to 172.23.0.77, dn_lease field to -1,
dn_macro field to "happy", and the dn_comment field to
"This is a test". Use lookup_dn to verify that the
original record has been changed correctly.
Case #17 delete_dn:
Using lookup_dn to find the record with a DN_QCIP of
<network address>+101, delete this record. Verify using
lookup_dn that this record can no longer be found.
Case #18 close_dn:
Close the open instance of the dhcp network container
<network address>. Verify that close_dn returns DSVC_SUCCESS.
Case #19 remove_dn:
Remove the dhcp network container <network address>.
Verify that the container is in fact gone using list.
FULL TEST
Description
This suite verifies that the dhcptab and dhcp network
table API function calls respond correctly when presented with
incorrect data. It also validates the MT-safeness of the API.
The test suite should allow any number of concurrent threads or
test suite processes to be invoked. The data must remain
consistent as measured at certain points during the test in
order for the test to be considered to have passed successfully.
Test Data
Item Description Application
==== =========== ===========
<location> Public module specific status, list,
path name to container open_dt,
directory (e.g. /var/dhcp remove_dt,
for 'files' data store). open_dn,
remove_dn
<Server IP> System under test's IP N/A
address.
dt records As follows: *_dt
SrootOpt s Vendor=SUNW.Ultra-1 SUNW.i86pc,1,ASCII,1,0
SrootIP4 s Vendor=SUNW.Ultra-1 SUNW.i86pc,2,IP,1,1
SrootNM s Vendor=SUNW.Ultra-1 SUNW.i86pc,3,ASCII,1,0
SrootPTH s Vendor=SUNW.Ultra-1 SUNW.i86pc,4,ASCII,1,0
SswapIP4 s Vendor=SUNW.Ultra-1 SUNW.i86pc,5,IP,1,1
SswapPTH s Vendor=SUNW.Ultra-1 SUNW.i86pc,6,ASCII,1,0
SbootFIL s Vendor=SUNW.Ultra-1 SUNW.i86pc,7,ASCII,1,0
Stz s Vendor=SUNW.Ultra-1 SUNW.i86pc,8,ASCII,1,0
SbootRS s Vendor=SUNW.Ultra-1 SUNW.i86pc,9,NUMBER,2,1
SinstIP4 s Vendor=SUNW.Ultra-1 SUNW.i86pc,10,IP,1,1
SinstNM s Vendor=SUNW.Ultra-1 SUNW.i86pc,11,ASCII,1,0
SinstPTH s Vendor=SUNW.Ultra-1 SUNW.i86pc,12,ASCII,1,0
SsysidCF s Vendor=SUNW.Ultra-1 SUNW.i86pc,13,ASCII,1,0
SjumpsCF s Vendor=SUNW.Ultra-1 SUNW.i86pc,14,ASCII,1,0
Sterm s Vendor=SUNW.Ultra-1 SUNW.i86pc,15,ASCII,1,0
Locale m :UTCoffst=-18000:
Solaris m :SrootIP4=129.148.174.27:SrootNM="atlantic": \
:SinstIP4=129.148.174.27:SinstNM="atlantic": \
:Sterm="xterm":BootSrvA=129.148.174.27:
sparc m \
:SrootPTH="/export/s28/solaris1of2.s28s_wos/latest/Solaris_8/Tools/Boot": \
:SinstPTH="/export/s28/solaris1of2.s28s_wos/latest":
sun4u m :Include=Solaris:Include=sparc:
i86pc m :Include=Solaris:SbootFIL="/platform/i86pc/kernel/unix": \
:SinstPTH="/export/s28/solaris1of2.s28x_wos/latest": \
:SrootPTH="/export/s28/solaris1of2.s28x_wos/latest/Solaris_8/Tools/Boot":
SUNW.i86pc m :Include=i86pc:
SUNW.Ultra-1 m :SbootFIL="/platform/sun4u/kernel/sparcv9/unix": \
:Include=sun4u:
172.21.0.0 m :Subnet=255.255.0.0:Router=172.21.0.2: \
:Broadcst=172.21.255.255:
atlantic m :Include=Locale:Timeserv=129.148.174.27:LeaseTim=3600: \
:LeaseNeg:Hostname:DNSdmain="snt.east.sun.com": \
:DNSserv=172.21.0.1:
010800207E8A02 m :Impress=172.22.255.27:
172.21.0.0 Dhcp network container. *_dn
dn records ~3000, as follows: *_dn
00 00 172.21.0.6 <Server IP> 0 atlantic
.
.
.
00 00 172.21.12.6 <Server IP> 0 atlantic
Case #1:
Disable the underlying data service. How this is done
is data service-dependent. Call each of status, version,
capability, list, open_dt, remove_dt, open_dn, and remove_dn.
PASS if the function returns DSVC_INTERNAL or
DSVC_MODULE_ERROR. What is returned is data service-specific. If
this test FAILs (e.g. a function returns DSVC_SUCCESS, terminate
the test run.
Cleanup: Reenable the underlying data service.
dhcptab Container API
=====================
Case #2 list_dt:
2.1. Invalid Location
Call function with an invalid <location>. PASS
if DSVC_INVAL is returned. If this case fails, abort
the test.
2.2. No container
Verify that list returns DSVC_NOENT.
Case #3 open_dt:
3.1. No container
Call function with DSVC_READ | DSVC_WRITE.
Verify that DSVC_NOENT is returned.
3.2. NON_BLOCK
Using DSVC_CREATE | DSVC_READ | DSVC_WRITE,
call open_dt to create a dhcptab container. Call
close_dt to close the handle. Call open_dt with
DSVC_READ | DSVC_WRITE | DSVC_NONBLOCK. Depending on
whether the public module supports it (see module doc),
the function should return either DSVC_SUCCESS or
DSVC_UNSUPPORTED. If NON_BLOCK access is supported,
endeavor to make the underlying service temporarily
unavailable (e.g: NIS+: checkpoint the database). Call
open_dt again with the same flags (read, write,
nonblock). open_dt must fail and return DSVC_BUSY.
Cleanup: re-enable underlying service, close the open
handle.
3.3. Container exists
Call function with DSVC_CREATE | DSVC_READ |
DSVC_WRITE. Verify that the function returns
DSVC_EXISTS.
Cleanup: remove the dhcptab container using remove_dt.
Case #4 add_dt:
Create and load the dhcptab as per Case #6 and Case #7.1
of the Basic Sanity Test.
4.1. Record exists
Attempt to add a test dhcptab record to the
dhcptab. Verify that DSVC_EXISTS is returned.
4.2. Busy
Close open handle with close_dt. Reopen with
DSVC_NONBLOCK specified. If nonblocking semantics are
supported, then make the data service busy through the
use of a data service-specific technique and attempt to
add an additional dhcptab record. Verify that DSVC_BUSY
is returned. Remove the data service busy condition and
reattempt the add operation. Verify that DSVC_SUCCESS is
returned. close_dt the container.
4.3. Read only
Close any open handles. Reopen the dhcptab with
DSVC_READ access only. If success is returned, attempt
to add a new record to the dhcptab. Verify that
DSVC_ACCESS is returned. close_dt the handle. Note that
some data store modules may return DSVC_UNSUPPORTED for
read-only access.
Cleanup: Close open handles, remove the dhcptab using
remove_dt.
Case #5 lookup_dt:
Create and load the dhcptab as per Case #6 and Case #7.1
of the Basic Sanity Test.
5.1. Record does not exist.
Produce a dhcptab container query that would not
be satisfied by the test data. Verify that DSVC_SUCCESS
is returned, and "records" is 0.
5.2. Busy
Close dhcptab handle with close_dt. Reopen with
DSVC_NONBLOCK specified. IF DSVC_SUCCESS is returned
(Nonblocking access is supported), using a data
service-specific technique for making the service busy,
attempt to perform a valid lookup of a dhcptab record.
Verify that DSVC_BUSY is returned. Remove the busy
condition, and reattempt the lookup. Verify that
DSVC_SUCCESS is returned, and that the data returned is
valid. close_dt the handle.
5.3. Write only
Reopen the dhcptab container with DSVC_WRITE
access only. If success is returned, attempt to perform
lookup_dt's using any syntactically legal query for the
dhcptab. Verify that DSVC_ACCESS is returned. close_dt
the handle.
5.4. Multiple matching records
Reopen the dhcptab container as per case
#6 and case #7.1 of the Basic Sanity Test. Using
modify_dt, change the dt_key for the SrootOpt symbol
such that the key value is now sun4u. Form a query which
simply specifies a DT_QKEY value of "sun4u". Verify that
exactly two records are returned, and that there values
are what is expected (one a macro, the other a symbol,
with the appropriate values).
Cleanup: Remove the dhcptab container using remove_dt.
Case #6 modify_dt:
Create and load the dhcptab container as per Case #6
and Case #7.1 of the Basic Sanity Test.
6.1. Unknown record
Fabricate dt_rec_t elements initialized with
data known not to exist in the dhcptab. Attempt to
modify these elements. Verify that DSVC_NOENT is
returned.
6.2. Update Collision #1
Use lookup_dt to find a valid dhcptab record.
Change the signature on the resultant dt_rec_t. Attempt
to modify the record. Verify that DSVC_COLLISION is
returned.
6.3. Update Collision #2
Use lookup_dt to find a valid dhcptab record.
Attempt to rename the record to one that already exists
(dt_key + dt_type). Verify that DSVC_EXISTS is returned.
6.4. Busy
Close the dhcptab with close_dt. Reopen with
DSVC_NONBLOCK specified. If DSVC_SUCCESS is returned (it
is supported), acquire a valid dhcptab record using
lookup_dt. Using a data service specific technique for
making the service busy, attempt to modify the value
(non-key fields) of the record. Verify that DSVC_BUSY is
returned. Remove the busy condition, and reattempt the
modify. Verify that DSVC_SUCCESS is returned.
Reacquire the record. Verify that the contents have been
suitably updated. close_dt the container.
6.5. Read only
Reopen the dhcptab with DSVC_READ access only.
If success is returned, locate a valid container record
using the appropriate query to lookup_dt. Modify the
contents of the record. Attempt to commit the modify to
the dhcptab. Verify that DSVC_ACCESS is returned.
close_dt the dhcptab handle.
Cleanup: Remove the dhcptab using remove_dt.
Case #7 free_dtrec_list:
This function should be used to release the results of
lookup_dt calls. Its operation must be validated by running this
test under bcheck with -memuse, and ensuring that no free blocks
remain after exit. Note that the test must be written with care
to make this case useful (free any allocated memory when it is
no longer needed).
Case #8 delete_dt:
Create and load the dhcptab container as per Case #6 and
Case #7.1 of the Basic Sanity Test.
8.1 Unknown record
Fabricate dt_rec_t containing a record known
not to exist in the dhcptab. Attempt to delete the
record. Verify that DSVC_NOENT is returned.
8.2 Busy
Close the dhcptab with close_dt. Reopen with
DSVC_NONBLOCK specified. If DSVC_SUCCESS is returned,
acquire a valid dhcptab container record using
lookup_dt. Using a data service specific technique for
making the service busy, attempt to delete the record.
Verify that DSVC_BUSY is returned. Remove the busy
condition, and reattempt the delete. Verify that
DSVC_SUCCESS is returned. Attempt to reacquire the
record. Verify that the record has in fact been deleted.
Close the dhcptab using close_dt.
8.3 Read only
Reopen the dhcptab container with DSVC_READ
access only. If success is returned, locate a valid
dhcptab record using an appropriate query to lookup_dt.
Attempt to delete the record. Verify that DSVC_ACCESS is
returned. Close the dhcptab using close_dt.
Cleanup: Remove the dhcptab using remove_dt.
Case #9 close_dt:
Verify that this function handles nonblocking semantics
correctly. Create a dhcptab as per case #6 of the Basic Sanity
Test, with the exception that DSVC_NONBLOCK is specified. If
nonblocking mode is supported, then using a data service
specific technique for making the service busy, attempt to close
the dhcptab handle returned by open_dt. Verify that DSVC_BUSY
is returned. Remove the busy condition, and reattempt the
close_dt. Verify that DSVC_SUCCESS is returned.
Cleanup: Remove the dhcptab container using remove_dt.
Case #10 remove_dt:
Verify that this function handles nonblocking semantics
correctly. Create a dhcptab container as per Case #6 of the Basic
Sanity Test. Close open handle using close_dt. Reopen with
DSVC_NONBLOCK specified. If nonblocking mode is supported, using
a data service specific technique for making the service busy,
attempt to remove the dhcptab container. Verify that DSVC_BUSY is
returned. Remove the busy condition, and reattempt the remove.
Verify that the dhcptab container is removed using list and that
the function returns DSVC_SUCCESS.
Cleanup: Close the open handle using close_dt (ignore result).
dhcp network Container API
==========================
Case #11 list_dn:
11.1. Invalid Location
Call function with an invalid <location>. PASS
if DSVC_INVAL is returned. If this case fails, abort
the test.
11.2. No container
Verify that list returns DSVC_NOENT.
Case #12 open_dn:
12.1. No container
Call function with DSVC_READ | DSVC_WRITE and
<network address>. Verify that DSVC_NOENT is returned.
12.2. NON_BLOCK
Using the flag values of DSVC_CREATE |
DSVC_READ | DSVC_WRITE | DSVC_NONBLOCK, the function
to create a dhcp network container called <network
address>. Depending on whether the public module
supports nonblocking semantics (see module doc),
the function should return either DSVC_SUCCESS or
DSVC_UNSUPPORTED. If NON_BLOCK access is supported,
endeavor to make the underlying service temporarily
unavailable (e.g: NIS+: checkpoint the database). Call
open_dn again with the same flags (read, write,
nonblock). open_dn must fail and return DSVC_BUSY.
Cleanup: re-enable underlying service, close the open
handle.
12.3. Container exists.
Using the flag values DSVC_CREATE | DSVC_READ |
DSVC_WRITE, attempt to open <network address>. Verify
that the function returns DSVC_EXISTS.
Cleanup: Remove the <network address> dhcp network
container using remove_dn.
Case #13 add_dn:
Create and load the <network address> dhcp network
container as per Case #13 and Case #14.1 of the Basic Sanity
Test.
13.1. Record exists
Attempt to add a test dhcp network record to
the <network address> dhcp network container. Verify
that DSVC_EXISTS is returned.
13.2. Busy
Close open handle with close_dn. Reopen with
DSVC_NONBLOCK specified. If nonblocking semantics are
supported, then make the data service busy through the
use of a data service-specific technique and attempt to
add an additional dhcp network record. Verify that
DSVC_BUSY is returned. Remove the data service busy
condition and reattempt the add operation. Verify that
DSVC_SUCCESS is returned. close_dn the container.
13.3. Read only
Close any open handles. Reopen the <network
address> dhcp network container with DSVC_READ access
only. If success is returned, attempt to add a new
record to the dhcp network container. Verify that
DSVC_ACCESS is returned. close_dn the handle. Note that
some data store modules may return DSVC_UNSUPPORTED for
read-only access.
Cleanup: Close open handles, remove the <network
address> dhcp network container using remove_dn.
Case #14 lookup_dn:
Create and load the <network address> dhcp network
container as per Case #13 and Case #14.1 of the Basic Sanity
Test.
14.1. Record does not exist.
Produce a dhcp network container query that
would not be satisfied by the test data. Verify that
DSVC_SUCCESS is returned, and "records" is 0.
14.2. Busy
Close the <network address> dhcp network handle
with close_dn. Reopen with DSVC_NONBLOCK specified. If
DSVC_SUCCESS is returned (Nonblocking access is
supported), using a data service-specific technique for
making the service busy, attempt to perform a valid
lookup of a dhcp network record. Verify that DSVC_BUSY
is returned. Remove the busy condition, and reattempt
the lookup. Verify that DSVC_SUCCESS is returned, and
that the data returned is valid. close_dn the handle.
14.3. Write only
Reopen the dhcp network container with DSVC_WRITE
access only. If success is returned, attempt to perform
lookup_dn's using any syntactically legal query for the
<network address> dhcp network container. Verify that
DSVC_ACCESS is returned. close_dn the handle.
14.4. Multiple matching records
Reopen the dhcp network container as per case
#13 and case #14.1 of the Basic Sanity Test. Using
modify_dn, change the dn_cid fields for records <network
address>+1 through <network address>+217 to 01BADDCAFE.
Form a query which simply specifies a DN_QCID of
01BADDCAFE. Confirm that exactly 216 records are
returned, and that their CIP range is correct.
Cleanup: Remove the <network address> dhcp network
container using remove_dn.
Case #15 modify_dn:
Create and load the <network address> dhcp network
container as per Case #13 and Case #14.1 of the Basic Sanity
Test.
15.1. Unknown record
Fabricate dn_rec_t elements initialized with
data known not to exist in the dhcp network container.
Attempt to modify these elements. Verify that DSVC_NOENT
is returned.
15.2. Update Collision #1
Use lookup_dn to find a valid dhcp network record.
Change the signature on the resultant dn_rec_t. Attempt
to modify the record. Verify that DSVC_COLLISION is
returned.
15.3. Update Collision #2
Use lookup_dn to find a valid dhcp network record.
Attempt to rename the record to one that already exists
(dn_cid, dn_flags, dn_cip, dn_sip, dn_lease, dn_macro).
Verify that DSVC_EXISTS is returned.
15.4. Busy
Close the dhcp network container with close_dn.
Reopen with DSVC_NONBLOCK specified. If DSVC_SUCCESS is
returned (nonblocking semantics are supported), acquire
a valid dhcp network record using lookup_dn. Using a
data service specific technique for making the service
busy, attempt to modify the value (non-key fields) of
the record. Verify that DSVC_BUSY is returned. Remove
the busy condition, and reattempt the modify. Verify
that DSVC_SUCCESS is returned. Reacquire the record.
Verify that the contents have been suitably updated.
close_dn the container.
15.5. Read only
Reopen the dhcp network container with DSVC_READ
access only. If success is returned, locate a valid
container record using the appropriate query to
lookup_dn. Modify the contents of the record. Attempt
to commit the modify to the dhcp network container.
Verify that DSVC_ACCESS is returned. close_dn the
dhcp network container handle.
Cleanup: Remove the dhcp network container using
remove_dn.
Case #16 free_dnrec_list:
This function should be used to release the results of
lookup_dn calls. Its operation must be validated by running this
test under bcheck with -memuse, and ensuring that no free blocks
remain after exit. Note that the test must be written with care
to make this case useful (free any allocated memory when it is
no longer needed).
Case #17 delete_dn:
Create and load the <network address> dhcp network
container as per Case #13 and Case #14.1 of the Basic Sanity
Test.
17.1 Unknown record
Fabricate dn_rec_t containing a record known
not to exist in the dhcp network container. Attempt
to delete the record. Verify that DSVC_NOENT is returned.
17.2 Busy
Close the dhcp network container with close_dn.
Reopen with DSVC_NONBLOCK specified. If DSVC_SUCCESS is
returned, acquire a valid dhcp network container record
using lookup_dn. Using a data service specific technique
for making the service busy, attempt to delete the record.
Verify that DSVC_BUSY is returned. Remove the busy
condition, and reattempt the delete. Verify that
DSVC_SUCCESS is returned. Attempt to reacquire the
record. Verify that the record has in fact been deleted.
Close the dhcp network container using close_dn.
17.3 Read only
Reopen the dhcp network container with DSVC_READ
access only. If success is returned, locate a valid
dhcp network record using an appropriate query to
lookup_dn. Attempt to delete the record. Verify that
DSVC_ACCESS is returned. Close the dhcp network
container using close_dn.
Cleanup: Remove the dhcp network container using
remove_dn.
Case #18 close_dn:
Verify that this function handles nonblocking semantics
correctly. Create the <network address> dhcp network container
as per case #13 of the Basic Sanity Test, with the exception
that DSVC_NONBLOCK is specified. If nonblocking mode is
supported, then using a data service specific technique for
making the service busy, attempt to close the dhcp network
handle returned by open_dn. Verify that DSVC_BUSY is returned.
Remove the busy condition, and reattempt the close_dn. Verify
that DSVC_SUCCESS is returned.
Cleanup: Remove the dhcp network container using remove_dn.
Case #19 remove_dn:
Verify that this function handles nonblocking semantics
correctly. Create the <network address> dhcp network container
as per Case #13 of the Basic Sanity Test, with the exception
that DSVC_NONBLOCK is specified. If nonblocking mode is
supported, using a data service specific technique for making
the service busy, attempt to remove the dhcp network container.
Verify that DSVC_BUSY is returned. Remove the busy condition,
and reattempt the remove. Verify that the <network address> dhcp
network container is removed using list and that the function
returns DSVC_SUCCESS.
Cleanup: Close the open handle using close_dn (ignore result).
Case #20 Multi-access stress
Public layer modules are not required to manage reference
counts for open instances. So while individual handles are
considered to be MT-safe (and parallel access to containers is
suitably protected), an application using the service provider
layer API must synchronize close and/or container remove
operations among threads such that no threads hold handles to a
container after the handle has been closed or the container has
been removed.
This case assumes a test which is multi-threaded, and
can run the following test using from 1 to THREADS threads. The
test can also be run in multiple concurrent processes.
The goal of this test is to ensure that the API is
MT-safe with respect to the containers and the records contained
within those containers. This goal is accomplished by verifying
that the end result of the test is consistent.
Tunable default values:
PROCESSES: 20
THREADS: 20
20.1 The dhcptab container test
20.1.1 open_dt
Create a dhcptab using DSVC_CREATE |
DSVC_READ | DSVC_WRITE. If DSVC_EXISTS is
returned, retry the open attempt w/o the
DSVC_CREATE flag. Log that this event occurred.
Handle will be used for balance of test. If any
other error occurs, terminate the test as
failed.
20.1.2 add_dt
Add the test data records to the dhcptab
container. If DSVC_EXISTS is returned, skip that
record, and continue attempting to add the other
records. Log that this event occurred. If any
other error occurs, terminate the test as
failed.
20.1.3 lookup_dt
Using DT_QKEY of "atlantic" and DT_QTYPE
of "m", find the atlantic record. Compare its
value against the test data. If it has
changed, then output a message to this affect.
If any error occurs, terminate the test as failed.
20.1.4 modify_dt
Using the results of 20.1.3, change the
record as follows. If it is no different from
the test data, change the value to:
:Timeserv=129.148.174.28:LeaseTim=86400: \
:Hostname:DNSdmain="east.sun.com":DNSserv=172.23.3.3:
If it doesn't match the test data
value, change the LeaseTim by incrementing it by
one. Attempt to update the record. If it fails
with DSVC_COLLISION, retry 20.1.3 and 20.1.4 for
three attempts. Log message if modify was
unsuccessful. If any other error occurs,
terminate the test as failed.
20.1.5 delete_dt
Use lookup_dt to find a DT_QKEY of
"SjumpsCF" and a DT_QTYPE of "s". If it does
not exist, log a message. If it does exist,
attempt to delete it. If DSVC_NOENT is returned,
log a message.
20.1.6 close_dt
Use close_dt to close the open handle.
If DSVC_NOENT is returned, log a message.
20.1.7 epilogue
Compare the resultant dhcptab container
to the test data. The only differences should be
a changed value of the atlantic macro as
expected from 20.1.4 and the SjumpsCF symbol
should be removed. Any other inconsistency means
the test has failed.
Clean up: Remove the dhcptab container.
20.2 The dhcp network table container test
20.2.1 open_dn
Create a <network address> dhcp network
table using DSVC_CREATE | DSVC_READ | DSVC_WRITE.
If DSVC_EXISTS is returned, retry the open
attempt w/o the DSVC_CREATE flag. Log that this
event occurred. Handle will be used for balance
of test. If any other error occurs, terminate
the test as failed.
20.2.2 add_dn
Add the test data records to the dhcp
network table container. If DSVC_EXISTS is
returned, skip that record, and continue
attempting to add the other records. Log that
this event occurred. If any other error occurs,
terminate the test as failed.
20.2.3 lookup_dn
Find the DN_QCIP of <network address>+102
record. Compare its value against the test data.
If it has changed, then output a message to this
affect. If any error occurs, terminate the test
as failed.
20.2.4 modify_dn
Using the results of 20.2.3, change the
record as follows. If it is no different from
the test data, change the value to:
01DEADBEEF 03 <network address>+102 172.23.3.3 941619403 Solaris
If it doesn't match the test data
value, change dn_lease by incrementing it by
one. Attempt to update the record. If it fails
with DSVC_COLLISION, retry 20.2.3 and 20.2.4 for
three attempts. Log message if modify was
unsuccessful. If any other error occurs,
terminate the test as failed.
20.2.5 delete_dn
Use lookup_dn to find a DN_QCIP of
<network address>+1001. If it does not exist,
log a message. If it does exist, attempt to
delete it. If DSVC_NOENT is returned, log a
message.
20.2.6 close_dn
Use close_dn to close the open handle.
If DSVC_NOENT is returned, log a message.
20.2.7 epilogue
The <network address> dhcp network
container should be consistent at the end of
a test run. The only differences should be a
changed value of the <network address>+102
record with the value as per 20.2.4 and the
lease time potentially incremented, as well as
the <network address>+1001 record missing.
Any other inconsistency means the test has
failed.
Cleanup: remove <network address> dhcp network
container.
20.3 Multi-process run
Run 20.1 and 20.2 in PROCESSES separate
processes.
20.4 Multi-threaded run, single process
Run 20.1 and 20.2 in THREADS separate threads
within a single process.
20.5 Multi-process, Multi-threaded run
Run 20.1 and 20.2 in PROCESSES separate
processes each spawning THREADS separate threads.
Case #21 Capacity
This test case endeavors to probe the stability and the
performance of the public module implementation when:
a) The data storage containers are filled to capacity.
b) The data storage containers are overfilled.
Note that while the number of records within a dhcptab
container could be infinite, the number of records within a dhcp
network container is bounded by the number of possible IP
addresses within the network represented by the container. If a
class A network is represented, there can be up to 16,777,215
possible records. The total number of records supported by a
public module (with some overhead for container information) is
the upper bound. That total number could be influenced by
settings in the underlying hosting data service, or by the
available memory or disk resources of the machine under test.
Since record sizes for dhcptab and dhcp network containers
differ, discovering the maximum number of possible records
requires some dynamic experimentation by the test itself.
21.1 Initialization
Call capability. The max number of possible
records for the environment under test will be contained
within the returned structure as will some estimate of
the operations per second claimed by the public module
in the run environment. A dhcptab will be created with
contains 1/3 of the maximum number of records. One or
more dhcp network containers will be created to contain
the balance of the records. A multithreaded program can
create the containers and load them with single threads,
one for each container. A consistent series of records
must be added to the dhcptab (monotonically increasing
symbol / macro records created, each with unique value
portions which could be calculated by the key fields of
the record). dhcp network container records simply contain
records unique by client IP address.
Initialization will stop when no more records can be
added to the system (XXX - what sort of error code would
be returned? DSVC_INTERNAL?). Operations per second
must be measured during the initialization process to
determine whether it is close to the advertised number
(XXX - how could this be verified?).
21.2 Modify
For every existing dhcp network record, modify
the lease time such that it is set to the number of
modify operations done during this subcase (first one ==
1, last 1+N). Measure operations per second during this
process.
21.3 Add
Attempt to add a new dhcptab and a new dhcp
network container(s) record. This operation should fail
(XXX expected results?).
21.4 Lookup
Form a configured number of legal queries (TBD
tunable) for the dhcptab and dhcp network container(s).
Validate that the data returned is what is expected
based upon knowledge of relationship between the record
being searched for and the expected value based upon the
search parameters. PASS if queries are successful.
Measure operations per second during this process for
comparison against advertised number.
21.5 Delete
Using lookup and delete, find and delete every
single record added by the test. Confirm that the
containers contain no records. Measure operations per
second during this process for comparison against the
advertised number.
Cleanup: Remove the containers.
REFERENCES
[1] "Enterprise DHCP Service Architecture Specification", mwc,
6/25/1999.
[2] "Enterprise Reference Hardware Platforms", mwc, 10/23/1999.