← Back to branch summary

~ubuntu-branches/ubuntu/wily/apparmor/wily

« back to all changes in this revision

Viewing changes to tests/regression/subdomain/README

  • Committer: Bazaar Package Importer
  • Author(s): Kees Cook
  • Date: 2011-04-27 10:38:07 UTC
  • mfrom: (5.1.118 natty)
  • Revision ID: james.westby@ubuntu.com-20110427103807-ym3rhwys6o84ith0
Tags: 2.6.1-2
debian/copyright: clarify for some full organization names.

Show diffs side-by-side

added added

removed removed

Lines of Context:
tests/regression/subdomain/README
1
 
Running tests
2
 
=============
3
 
 
4
 
Type "make tests" at the shell prompt, this will make the subprograms
5
 
and run the tests.
6
 
 
7
 
You must be root to execute make tests (a requirement of subdomain).
8
 
 
9
 
(There is also a 'make alltests', which adds a test for bug that, when
10
 
triggered, would cause the kernel to crash.)
11
 
 
12
 
Test output
13
 
===========
14
 
 
15
 
No output is displayed for a passing test.  The makefile will output
16
 
        running <testname> for each test.
17
 
 
18
 
Output other than this indicates a problem.
19
 
 
20
 
There are three typical failure scenarios:
21
 
        - Test failed when it was expected to pass
22
 
        - Test passed when it was expected to fail
23
 
        - Unexpected shell error - the test harness encountered an unexpected
24
 
                error.
25
 
 
26
 
 
27
 
Changing environment variables
28
 
==============================
29
 
 
30
 
Common user changeable environment variables are stored in the file
31
 
'uservars.inc'.  Currently the path to the tmp directory, the path
32
 
to the subdomain_parser executable, and any additional arguments to give
33
 
to the parser are specified in this configuration file.
34
 
 
35
 
(Note: the tmp directory specified in uservars.inc will have an added
36
 
random string appended to it by the mktemp(1) program.)
37
 
 
38
 
Debugging test failures
39
 
=======================
40
 
 
41
 
In the event of a failure run the individual test harness using the -r (or 
42
 
-retain) option.  This will not remove the temporary test directory and will 
43
 
display it's path.  Inside the directory is a script called 'runtest' which 
44
 
will rerun the last failed command. 
45
 
 
46
 
Example:
47
 
 
48
 
# sh unlink.sh -r
49
 
Files retained in: /tmp/sdtest.25406-19681
50
 
 
51
 
#ls -l /tmp/sdtest.25406-19681
52
 
total 3
53
 
-rw-r--r--    1 root     root            0 Jul  2 11:51 file
54
 
-rw-r--r--    1 root     root           25 Jul  2 11:51 output.unlink
55
 
-rw-r--r--    1 root     root          182 Jul  2 11:51 profile
56
 
-rw-r--r--    1 root     root          292 Jul  2 11:51 runtest
57
 
 
58
 
 
59
 
Note that the contents of this directory (when -r is specified) is the output
60
 
of the final test contained within the controlling test harness, in this case
61
 
unlink.sh.   If the harness passed, then output.unlink will contain the output
62
 
from the final run of the executable (which may indicate an expected error).
63
 
If there was an unexpected error (failed when pass was expected or passed when
64
 
failure was expected, or an unexpected test harness error), the controlling 
65
 
test harness will abort processing further tests and the contents of the 
66
 
directory will contain the files for the failed subtest.
67
 
 
68
 
It may be necessary to create certain temp files in this directory in order to 
69
 
have the test function correctly, see the subdomain profile 'profile' in the 
70
 
directory in order to determine which files may need to be created to support
71
 
the executable.
72
 
 
73
 
In order to debug more complicated test failures such as an expected 
74
 
shell error (test harness error) it is usually necessary to rerun the test with 
75
 
debugging enabled, for example:
76
 
 
77
 
# sh -x unlink.sh
78
 
 
79
 
 
80
 
Adding new tests
81
 
================
82
 
 
83
 
The test harness is designed to make adding new tests fairly simply.
84
 
 
85
 
Each test consists of one controlling shell script and one or more executable
86
 
files.  
87
 
 
88
 
The file 'prologue.inc' must be loaded into the shell script.  This file 
89
 
contains the controlling logic and supporting shell functions.
90
 
 
91
 
By default, prologue.inc assumes the test binary is the same name as the shell
92
 
script, with '.sh' removed.  For test scripts with only one executable this 
93
 
makes things simple.  You may want to have a single shell script run multiple
94
 
executables (syscall.sh for example). In this case, the 'settest' function is
95
 
used to select a new binary executable for this test.
96
 
 
97
 
The 'genprofile' function generates a profile based on passed arguments.  
98
 
The function automatically adds the necessary shared libraries and output 
99
 
files necessary to support the execution, it is not necessary to specify 
100
 
these manually.  Therefore a call to genprofile without arguments will build 
101
 
a profile allowing the executable to run but without any additional access.
102
 
Specifying additional arguments to genprofile in the form of <filename>:<perm>
103
 
will allow additional access.  
104
 
 
105
 
Support for changehat subprofiles is provided by the 'hat:<hatname>'
106
 
argument to genprofile. This will create a hat within the profile named
107
 
<hatname>. All following rules (file, net, or cap) up to the next "hat:"
108
 
argument or the end of the argument list will be included within this hat.
109
 
 
110
 
Support for multiple profiles within a single load (for example for
111
 
test that want to domain tansition to another profile) is supported by
112
 
the "image' argument to genprofile. This keyword preceeded by a '--'
113
 
seperator terminates the previous profile and creates a new profile for
114
 
the specified executable image.
115
 
 
116
 
Together, 'image' and 'hat:' allow complex profiles including subhats and
117
 
domain transitions to be specified via a single invocation of genprofile.
118
 
 
119
 
[Note: the old "-- subhat=<hatname>" mechanism for specifying hats is
120
 
 no longer supported.]
121
 
 
122
 
Executing a test is achieved by calling the 'runchecktest' function which
123
 
will run either the executable matching the name of the shell script, or 
124
 
specified by settest.  The first argument is a brief description of what the
125
 
executable does in this mode, which is displayed in the event of an error.
126
 
The second argument is either "pass" or "fail" indicating whether the test
127
 
is expected to pass or fail.  The executable is expected to output "PASS"
128
 
for success and "FAIL: <error message>" in the event of a failure.  If the
129
 
executable outputs something other than this, the controlling shell script
130
 
will interpret this as a test failure and output "unable to run test sub
131
 
executable" and terminate.  Remaining arguments to runchecktest are passed
132
 
to the executable as argv[1] .. argv[n].
133
 
 
134
 
The runchecktest command executes and checks the test serially.  If a test
135
 
requires to be run in the background, so that the shell may do subsequent
136
 
operations, such as sending it a signal before checking it's output, this is
137
 
accomplished by separately calling 'runtestbg' and 'checktestbg' instead
138
 
of calling 'runchecktest'.
139
 
 
140
 
Profile loading, replacing and unloading is automatically handled by the 
141
 
shell script (via prologue.inc).  Also, cleanup (tempfile removal and 
142
 
profile unloading) on exit is automatic.
143
 
 
144
 
As an example, the text shell script for exec (exec.sh) is 24 lines and
145
 
may be used as a template for creating new simple tests (changehat.sh is
146
 
a good template for subprofile tests and rw.sh is a template for tests
147
 
requiring signal passing)
148
 
 
149
 
        #! /bin/bash
150
 
        
151
 
        pwd=`dirname $0`
152
 
        pwd=`cd $pwd ; pwd`
153
 
        
154
 
        <bin must be set prior to including prologue.inc. This is the only>
155
 
        <requirement placed on the shell script author by prologue.inc>
156
 
        bin=$pwd
157
 
        
158
 
        <prologie.inc must be included before running any tests>
159
 
        . $bin/prologue.inc
160
 
        
161
 
        <variable definitions used by this script?
162
 
        file=/bin/true
163
 
        okperm=x
164
 
        badperm=r
165
 
        
166
 
        # PASS TEST
167
 
        
168
 
        <generate a profile allowing x access to /bin/true>
169
 
        genprofile $file:$okperm
170
 
        
171
 
        <run this test (exec) passing /bin/true as argv[1]>
172
 
        <check it's output, it is expected to pass>
173
 
        runchecktest "EXEC with x" pass $file
174
 
        
175
 
        # NOLINK PERMTEST
176
 
        <generate a new profile allowing only r access to /bin/true>
177
 
        <subdomain_parser will automatically be invoked in -r mode>
178
 
        genprofile $file:$badperm
179
 
 
180
 
        <run this test (exec) passing /bin/true as argv[1]>
181
 
        <check it's output, it is expected to FAIL>
182
 
        runchecktest "EXEC no x" fail $file
183
 
 
184
 
        <Thats it. Exit status $rc is automatically returned by epilogue.inc>
185
 
 
186
 
Additional documentation
187
 
========================
188
 
 
189
 
See the file 'subdomain_test.txt'
190
 
 
191
 
Supporting files
192
 
================
193
 
 
194
 
strace.sh       Not a test harness, used to support strace testing.
195
 
mkprofile.sh    Not a test harness, used to generate subdomain profiles.
196
 
prologue.inc    Must be dotted (included) into the test harness. Provides
197
 
                support routines.
198
 
epilogue.inc    Cleanup support, automatically called upon successful or
199
 
                unsuccessful exit
200
 
uservars.inc    Contains variables that may need to be changed per user.
201
 
 
202
 
Makefile        Makefile for building or running tests. Use 'make' to build,
203
 
                'make tests' to run.
204
 
 
205
 
*.sh            Controlling test harness
206
 
*.c             Test executable.
207
 
 
208
 
Disabled tests
209
 
==============
210
 
 
211
 
Symlink mediation (symlink.sh) in AppArmor has been disabled.
212
 
It is too easy to defeat by creating a relative symlink and subsequently
213
 
moving the link.
214
 
 
215
 
Current failures
216
 
================
217
 
 
218
 
1) Changehat_misc
219
 
 
220
 
   THIS IS NOT AN ERROR - per se.
221
 
   Two killed messages will be output. 
222
 
   This is not an error, rather a sign that bash noticed the kernel had killed 
223
 
   a process which was attempting to use a bogus MAGIC number.  Alas, there is 
224
 
   no way to get bash to not print this diagnostic
225
 
 
226
 
3) Ptrace
227
 
        Error: open passed. Test 'STRACE OPEN (x confinement)' 
228
 
        was expected to 'fail'
229
 
 
230
 
   Regression from 2.4.18 to 2.4.20. (We aren't sure on the first
231
 
   endpoint, and the problem still happens in 2.4.20-20_imnx_10smp.)
232
 
 
233
 
4) Open
234
 
        Error: open passed. Test 'OPEN W (create)' was expected to 'fail'
235
 
 
236
 
   LSM issue.  Flags passed to inode_permission are 0 if O_CREAT is used to
237
 
   open file.  Need to submit a patch to inode_create hook to receive the
238
 
   O_RDWR flags. See https://bugs.wirex.com/show_bug.cgi?id=2885