From: Paul Moore <paul@xxxxxxxxxxxxxx> Also better integrate the InfiniBand instructions into the document. Signed-off-by: Paul Moore <paul@xxxxxxxxxxxxxx> --- README | 191 ----------------------------------------------------- README.md | 220 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 220 insertions(+), 191 deletions(-) delete mode 100644 README create mode 100644 README.md diff --git a/README b/README deleted file mode 100644 index e832f49..0000000 --- a/README +++ /dev/null @@ -1,191 +0,0 @@ -This directory contains the functional test suite for the LSM-based -SELinux security module. Please refer to the test report available in -doc/tests for complete documentation for this test suite. This -README only covers a subset of that report, specifically the sections -on running the tests and adding new tests. - -PREREQUISITES -------------- - -Kernel Configuration --------------------- -Your kernel should have been built with the configuration options -specified by the defconfig file in this directory to run this testsuite. -You can merge the provided defconfig file with your existing .config -file (or one generated via e.g. make localmodconfig or other commands) -using the kernel ./scripts/kconfig/merge_config.sh script as follows: - -cd linux -# Assumes that you have already created a .config file with your base config. -# If you don't have one, generate one using make localmodconfig or other -# suitable command. -./scripts/kconfig/merge_config.sh .config /path/to/selinux-testsuite/defconfig - -Some of the config options may not be set in the final config because -they are unnecessary based on your base config, e.g. you only need the -CONFIG_*_FS_SECURITY option to be enabled for the particular -filesystem type being used for the testing. - -Do not set CONFIG_SECURITY_SELINUX_POLICYDB_VERSION_MAX; it is an -option for legacy distributions (Fedora 3 and 4). - -You should not enable any other security modules in your kernel -configuration unless you use the security= option to select a module -at boot time. Only one primary security module may be active at a -time. - -Userland and Base Policy ------------------------- -The testsuite has the following userspace dependencies on Fedora -or RHEL beyond a minimal install: -perl-Test # test harness used by the testsuite -perl-Test-Harness # test harness used by the testsuite -perl-Test-Simple # for Test::More -selinux-policy-devel # to build the test policy -gcc # to build the test programs -libselinux-devel # to build some of the test programs -net-tools # for ifconfig, used by capable_net/test -netlabel_tools # to load NetLabel configuration during inet_socket tests -iptables # to load iptables SECMARK rules during inet_socket tests -libibverbs-devel # to build ibpkey test program. - -yum install perl-Test perl-Test-Harness perl-Test-Simple selinux-policy-devel gcc libselinux-devel net-tools netlabel_tools iptables libibverbs-devel - -The testsuite requires a pre-existing base policy configuration of -SELinux, using either the old example policy or the reference policy -as the baseline. It also requires the core SELinux userland packages -(libsepol, checkpolicy, libselinux, policycoreutils, and if using -modular policy, libsemanage) to be installed. The test scripts also -rely upon the SELinux extensions being integrated into the coreutils -package, with support for the chcon and runcon commands as well as the -SELinux options to existing utilities such as ls and mkdir. - -If the base distribution does not include the SELinux userland, then -the source code for the core SELinux userland packages can be obtained from: -https://github.com/SELinuxProject/selinux/wiki/Releases - -If the base distribution does not include a policy configuration, then -the reference policy can be obtained from: -https://github.com/TresysTechnology/refpolicy/wiki/DownloadRelease - -RUNNING THE TESTS ------------------ -Create a shell with the unconfined_r or sysadm_r role and the Linux superuser -identity, e.g.: - newrole -r sysadm_r # -strict or -mls policy only - su - -Check whether the SELinux kernel is in enforcing mode by running -'getenforce'. If it is in permissive mode, toggle it into enforcing -mode by running 'setenforce 1'. - -Ensure that expand-check = 0 in /etc/selinux/semanage.conf; if not, -edit it accordingly. - -To run the test suite, you can just do a 'make test' from the top-level -directory or you can follow these broken-out steps: - -1) Load the test policy configuration as follows: - make -C policy load - -2) Build and run the test suite from the tests subdirectory as follows: - make -C tests test - -3) Unload the test policy configuration as follows: - make -C policy unload - -The broken-out steps allow you to run the tests multiple times without -loading policy each time. - -4) Review the test results. - -As each test script is run, the name of the script will be displayed -followed by a status. After running all of the test scripts, a -summary of the test results will be displayed. If all tests were -successful, something similar to the following summary will be -displayed (the specific numbers will vary): - -All tests successful. -Files=7, Tests=16, 2 wallclock secs ( 0.17 cusr + 0.12 csys = 0.29 CPU) - -Otherwise, if one or more tests failed, the script will report -statistics on the number of tests that succeeded and will include a -table summarizing which tests had failed. The output will be similar -to the following text, which shows that a total of three tests have -failed: - -Failed Test Status Wstat Total Fail Failed List of failed -------------------------------------------------------------------------------- -entrypoint/test 2 1 50.00% 1 -inherit/test 3 2 66.67% 1-2 -Failed 2/7 test scripts, 71.43% okay. 3/16 subtests failed, 81.25% okay. -make: *** [test] Error 255 - -You can also run individual test scripts by hand, e.g. running -./entrypoint/test, to see the raw output of the test script. This is -particularly useful if a particular test within a given script fails -in order to help identify the cause. When run by hand, the test -script displays the expected number of tests, a status for each test, -and any error messages from the test script or its helper programs. - -Please report any failures to the selinux@xxxxxxxxxxxxx mailing list, -including a copy of the test summary output, the raw output from test -scripts that failed, a description of your base platform, and the -particular release of SELinux that you are using. - - -ADDING NEW TESTS ----------------- -The functional test suite is not yet complete, so we still need -additional tests to be written. See the GitHub issues tracker -for the list of tests that still need to be written, -https://github.com/SELinuxProject/selinux-testsuite/issues - -To add a new test, create a new test policy file and a new test -script. The new test policy file should be added to the -policy directory and should contain a set of test -domains and types specifically designed for the test. For the test -script, create a new subdirectory in the tests subdirectory, populate it -with at least a Makefile and a test perl script and add it to the -SUBDIRS definition in the Makefile file. - -The Makefile must contain 'all' and 'clean' targets, even if they are -empty, to support the build system. The test script must run with no -arguments and must comply with the perl automated test format. The -simplest way to comply with the Perl automated test format is to use -the Perl Test module. To do this, first include the following -statement at the top of the test Perl script: - use Test; - -Next, include a declaration that specifies how many tests the script -will run; the statement to include will be similar to: - BEGIN { plan tests => 2} # run two tests - -You can then use the 'ok' subroutine to print results - ok(1); # success - ok(0); # failure - ok(0,1); # failure, got '0', expected '1' - ok($results, 0); # success if $results == 0, failure otherwise - -Standard error is ignored. - -In general, the scripts need to know where they are located so that -they can avoid hard-coded paths. Use the following line of Perl to -establish a base directory (based on the path of the script -executable). This won't always be accurate, but will work for this -test harness/configuration. - $basedir = $0; $basedir =~ s|(.*)/[^/]*|$1|; - -INFINIBAND TESTS ----------------- -Because running Infiniband tests requires specialized hardware you must -set up a configuration file for these tests. The tests are disabled by -default. See comments in the configuration file for info. The endport -tests use smpquery, for Fedora it's provided by the infiniband-diags -package. - -Infiniband PKey test conf file: -tests/infiniband_pkey/ibpkey_test.conf - -Infiniband Endport test conf file: -tests/infiniband_endport/ibendport_test.conf diff --git a/README.md b/README.md new file mode 100644 index 0000000..c9f3b2b --- /dev/null +++ b/README.md @@ -0,0 +1,220 @@ +Basic SELinux Regression Test Suite for the Linux Kernel +=============================================================================== +https://github.com/SELinuxProject/selinux-testsuite + +This directory contains the functional test suite for the LSM-based SELinux +security module. Please refer to the test report available in `doc/tests` for +complete documentation for this test suite. This README only covers a subset +of that report, specifically the sections on running the tests and adding new +tests. + +## Prerequisites + +### Kernel Configuration + +Your kernel should have been built with the configuration options specified by +the `defconfig` file in this directory to run this testsuite. If you already +have a working kernel configuration you can merge the provided `defconfig` file +with your existing kernel `.config` file (or one generated via e.g. +`make localmodconfig` or other commands) using the kernel +`./scripts/kconfig/merge_config.sh` script as follows: + + # cd linux + # ./scripts/kconfig/merge_config.sh .config /path/to/selinux-testsuite/defconfig + +Some of the config options may not be set in the final config because they are +unnecessary based on your base config, e.g. you only need the +`CONFIG_*_FS_SECURITY` option to be enabled for the particular filesystem type +being used for the testing. + +Do not set `CONFIG_SECURITY_SELINUX_POLICYDB_VERSION_MAX`; it is an option for +legacy distributions (Fedora 3 and 4). + +You should not enable any other security modules in your kernel configuration +unless you use the `security=` option to select a module at boot time. Only +one primary security module may be active at a time. + +### Userland and Base Policy + +On a Fedora/RHEL based system the testsuite has the following userspace +dependencies beyond a minimal install (other Linux distributions should have +similar dependencies): + +* perl-Test _(test harness used by the testsuite)_ +* perl-Test-Harness _(test harness used by the testsuite)_ +* perl-Test-Simple _(for `Test::More`)_ +* selinux-policy-devel _(to build the test policy)_ +* gcc _(to build the test programs)_ +* libselinux-devel _(to build some of the test programs)_ +* net-tools _(for `ifconfig`, used by `capable_net/test`)_ +* netlabel\_tools _(to load NetLabel configuration during `inet_socket` tests)_ +* iptables _(to load the `iptables SECMARK` rules during `inet_socket` tests)_ + +On a modern Fedora system you can install these dependencies with the +following command: + + # dnf install perl-Test \ + perl-Test-Harness \ + perl-Test-Simple \ + selinux-policy-devel \ + gcc \ + libselinux-devel \ + net-tools \ + netlabel_tools \ + iptables + +The testsuite requires a pre-existing base policy configuration of SELinux, +using either the old example policy or the reference policy as the baseline. +It also requires the core SELinux userland packages (`libsepol`, `checkpolicy`, +`libselinux`, `policycoreutils`, and if using modular policy, `libsemanage`) +to be installed. The test scripts also rely upon the SELinux extensions being +integrated into the `coreutils` package, with support for the `chcon` and +`runcon` commands as well as the SELinux options to existing utilities such as +`ls` and `mkdir`. + +If the base distribution does not include the SELinux userland, then the +source code for the core SELinux userland packages can be obtained from: + +* https://github.com/SELinuxProject/selinux/wiki/Releases + +If the base distribution does not include a policy configuration, then +the reference policy can be obtained from: + +* https://github.com/TresysTechnology/refpolicy/wiki/DownloadRelease + +### Optional Prerequisites + +#### InfiniBand + +The InfiniBand tests require specialized hardware and are not enabled by +default. If you have InfiniBand hardware on your system and wish to enable +the InfiniBand tests you will need to install some additional packages, the +list below is for Fedora/RHEL but other Linux distributions should have +similar packages: + +* libibverbs-devel _(to build the `ibpkey` test program)_ +* infiniband-diags _(for `smpquery` used by `infiniband_endport/test`)_ + +On a modern Fedora system you can install these dependencies with the +following command: + + # dnf install libibverbs-devel infiniband-diags + +Once the necessary packages have been installed, the tests need to be enabled +and configured for your specific hardware configuration. The test +configuration files are below, and each includes comments to help configure +the tests: + + tests/infiniband_pkey/ibpkey_test.conf + tests/infiniband_endport/ibendport_test.conf + +## Running the Tests + +Create a shell with the `unconfined_r` or `sysadm_r` role and the Linux +superuser identity, e.g.: + + # newrole -r sysadm_r # -strict or -mls policy only + # su + +Check whether the SELinux kernel is in enforcing mode by running `getenforce`. +If it is in permissive mode, toggle it into enforcing mode by running +`setenforce 1`. + +Ensure that `expand-check = 0` in `/etc/selinux/semanage.conf`; if not, edit it +accordingly. + +To run the test suite, you can just do a `make test` from the top-level +directory or you can follow these broken-out steps: + +1) Load the test policy configuration as follows: + + `# make -C policy load` + +2) Build and run the test suite from the tests subdirectory as follows: + + `# make -C tests test` + +3) Unload the test policy configuration as follows: + + `# make -C policy unload` + +The broken-out steps allow you to run the tests multiple times without +loading policy each time. + +4) Review the test results. + +As each test script is run, the name of the script will be displayed followed +by a status. After running all of the test scripts, a summary of the test +results will be displayed. If all tests were successful, something similar to +the following summary will be displayed (the specific numbers will vary): + + All tests successful. + Files=7, Tests=16, 2 wallclock secs ( 0.17 cusr + 0.12 csys = 0.29 CPU) + +Otherwise, if one or more tests failed, the script will report statistics on +the number of tests that succeeded and will include a table summarizing which +tests had failed. The output will be similar to the following text, which +shows that a total of three tests have failed: + + Failed Test Status Wstat Total Fail Failed List of failed + ------------------------------------------------------------------------------- + entrypoint/test 2 1 50.00% 1 + inherit/test 3 2 66.67% 1-2 + Failed 2/7 test scripts, 71.43% okay. 3/16 subtests failed, 81.25% okay. + make: *** [test] Error 255 + +You can also run individual test scripts by hand, e.g. running +`./entrypoint/test`, to see the raw output of the test script. This is +particularly useful if a particular test within a given script fails in order +to help identify the cause. When run by hand, the test script displays the +expected number of tests, a status for each test, and any error messages from +the test script or its helper programs. + +Please report any failures to the selinux@xxxxxxxxxxxxx mailing list, +including a copy of the test summary output, the raw output from test scripts +that failed, a description of your base platform, and the particular release +of SELinux that you are using. + +## Adding New Tests + +The functional test suite is not yet complete, so we still need additional +tests to be written. See the GitHub issues tracker for the list of tests that +still need to be written: + +* https://github.com/SELinuxProject/selinux-testsuite/issues + +To add a new test, create a new test policy file and a new test script. The +new test policy file should be added to the policy directory and should +contain a set of test domains and types specifically designed for the test. +For the test script, create a new subdirectory in the tests subdirectory, +populate it with at least a Makefile and a test perl script and add it to the +`SUBDIRS` definition in the Makefile file. + +The Makefile must contain 'all' and 'clean' targets, even if they are empty, +to support the build system. The test script must run with no arguments and +must comply with the perl automated test format. The simplest way to comply +with the Perl automated test format is to use the Perl Test module. To do +this, first include the following statement at the top of the test Perl script: + + use Test; + +Next, include a declaration that specifies how many tests the script will run; +the statement to include will be similar to: + + BEGIN { plan tests => 2} # run two tests + +You can then use the 'ok' subroutine to print results: + + ok(1); # success + ok(0); # failure + ok(0,1); # failure, got '0', expected '1' + ok($results, 0); # success if $results == 0, failure otherwise + +Standard error is ignored. + +In general, the scripts need to know where they are located so that they can +avoid hard-coded paths. Use the following line of Perl to establish a base +directory (based on the path of the script executable). This won't always be +accurate, but will work for this test harness/configuration. + + $basedir = $0; $basedir =~ s|(.*)/[^/]*|$1|;
