Merge pull request #97 from jpichon/docs_update

Add contributing, dev, and troubleshooting documentation

README

@@ -1,4 +1,4 @@
-This repository contains OpenStack policy workarounds 
+This repository contains OpenStack policy workarounds
 for EL6 and EL7 and derivatives.  Each release has its
 own corresponsing branch.
 
@@ -16,9 +16,5 @@ https://bugzilla.redhat.com/
 Running the tests
 -----------------
 
-1. Install the selinux-policy-devel package
-2. Ensure the path /usr/share/openstack-selinux/master exists
-3. From your local openstack-selinux repository, run the following
-   command as root:
-
-    $ make clean all install check
+See the doc/ directory for more information on reporting and fixing
+bugs as well as troubleshooting tips.

doc/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+How to report a bug
+-------------------
+
+1. Set the system to Permissive and reproduce the issue (*)
+2. When reporting the issue, include the permissive audit logs as well
+3. The `audit2allow` output can be helpful to include in the report
+   when it's limited to the denials relevant to the issue, but it is
+   not enough on its own. It's essential to also include the actual AVC
+   denials (and ideally, the full permissive audit logs around the time
+   the issue is triggered.)
+
+If a bug doesn't already exist on Launchpad or Bugzilla, create a [RDO
+bug](https://bugzilla.redhat.com/enter_bug.cgi?product=RDO) with the
+`openstack-selinux` component. Having a bug number is necessary to add
+unit tests.
+
+(*) In Enforcing mode, SELinux stops at the first denial which can hide
+    more of them. Permissive mode enables us to see the full list of
+    AVC denials, so that they can be resolved all at once rather than
+    one at a time.
+
+How to run the tests
+--------------------
+
+1. Install the `selinux-policy-devel` package
+2. Ensure the path `/usr/share/openstack-selinux/master` exists
+3. From your local openstack-selinux repository, run the following
+   command as root:
+
+        $ make clean all install check
+
+It is recommended to use a VM for this.
+
+Fixing an issue
+----------------
+
+If you are certain a new SELinux rule is necessary, consider a patch
+with the minimum amount of new rules. If some of the rules are too
+wide, the original code may need to change to allow more restricted
+policy changes. If that's really not possible, the new rules may need
+to be hidden behind a new boolean that stays turned off by default,
+except in specific deployment scenarios.
+
+When preparing the patch, include the denials fixed by the new rule in
+a test file under tests/ to confirm the fix and avoid future
+regressions.
+
+Note: a test file won't help in the case of booleans turned off by
+default. In that case, include the denials in the commit message
+instead to help reviewers with understanding the issue being resolved
+and keeping a record.

doc/TROUBLESHOOTING.md

@@ -0,0 +1,45 @@
+Here is a list of common issues and tips on how to debug them.
+
+How to resolve 'SELinux boolean os_enable_vtpm does not exist.'?
+----------------------------------------------------------------
+How to resolve 'Missing os-ovs! [...] Found XX missing modules' errors?
+-----------------------------------------------------------------------
+
+Either of these errors means that the `openstack-selinux` package could
+not be installed properly, which can happen for a number of
+reasons. Usually, it indicates a missing dependency or that a symbol
+required by a policy is not defined on the system.
+
+A few tips that may help to debug:
+
+* Try to reinstall the package and look carefully at the output. There
+  should be some kind of warning. If you need to open a bug, make sure
+  to include this output in the report as this is the real error.
+
+        # dnf reinstall openstack-selinux
+
+* Confirm that `container-selinux` is present and also installed
+  correctly.` openstack-selinux` depends on the symbols defined in it
+  and will also fail if the package isn't properly installed on the
+  system. You can check that by running the following command (this may
+  require installing `setools-console`):
+
+        $ seinfo --type | grep container
+
+  This should return at least a dozen types. If seinfo only returns
+  three container symbols or less, `container-selinux` is missing or
+  not installed properly. You can try to reinstall the rpm to look for
+  a trace with more information.
+
+Switching to Permissive mode resolves my problem but there are no denials in the audit logs
+-------------------------------------------------------------------------------------------
+
+You may be hitting an issue with `dontaudit` rules. You can temporarily
+allow SELinux to log these with the following command:
+
+    # semodule -DB
+
+This will rebuild the policy. Once you have reproduced the issue and
+are able to check the logs, you can revert back with:
+
+    # semodule -B