diff --git a/selinux/README.md b/selinux/README.md
new file mode 100644
index 00000000..02e23d6a
--- /dev/null
+++ b/selinux/README.md
@@ -0,0 +1,65 @@
+# SELiunx and osbuild
+
+SELinux labels for files are store as extended attributes under the
+`security.selinux` prefix.
+
+## File system tree labelling
+All stages, including the `org.osbuild.rpm` stage are run inside a
+container which will indicate to all tools, including rpm scriptles
+that SELinux is disabled.
+
+Labels are manually applied to the file system tree via a specialised
+`org.osbuild.selinux` stage. This stage should therefore be at the
+very end of the pipeline that is building the tree so that all files
+are properly labelled.
+
+## Container peculiarities and policy differences
+
+SELinux is not namespaced which means there is only one global
+policy inside the Linux kernel. Since the kernel is shared by all
+containers, the policy that is loaded in the kernel applies to all
+containers as well.
+
+Labels are verified against the active policy in the kernel when
+writing (`setxattr`) but also when reading them (`getxattr`) as
+long as selinux is activated for the kernel (i.e. on the host).
+
+To read or write labels that are not included in the currently
+active policy, the `CAP_MAC_ADMIN` capability(7) is needed. If
+a process does not have this policy the following will happen
+when trying to write or read the label:
+
+When trying to write a label that is unknown to the currently
+active policy, the kernel will reject it and the call to
+`setxattr` will fail with `EINVAL` resulting in "Invalid argument"
+errors from the corresponding tooling.
+
+When trying to read a label that is unknown to the currently
+active policy, the kernel will "pretend" the file is not labelled and
+return `system_u:object_r:unlabeled_t:s0` as label. Thus a file with
+an unknown label (unknown to the host kernel) is indistinguishable
+from an unlabelled file.
+
+In RHEL and Fedora's SELinux policy, only very few programs can
+gain or retain the`CAP_MAC_ADMIN` capability, even if the current
+user is `unconfined` or `sysadm`. Normal tools like `cp`, `ls`,
+`stat`, or `tar` do *not* have this capability meaning that
+inspecting the labels for files and folders will result in
+`unlabeled_t` for unknown (to the host) labels.
+
+### Custom OSBuild SElinux Policy
+
+On RHEL and Fedora, the SELinux policy has a few contexts that
+allow `CAP_MAC_ADMIN`, most notably `install_t` and `setfiles_mac`.
+The latter is a policy for the `setfiles` binary, which is used
+by the`org.osbuild.selinux` stage to label files. But to be able
+to transition into `setfiles_mac`, the calling program must have a
+special transition rule allowing this. Therefore osbuild uses a
+custom policy with specialised labels for osbuild executables such
+as stages, runners and the main binary: `osbuild_t`. Then a domain
+transition rule is enabled that allows `setfiles` to transition to
+`setfiles_mac` from `osbuild`. From `selinux/osbuild.te`:
+
+    # execute setfiles in the setfiles_mac domain
+    # when in the osbuild_t domain
+    seutil_domtrans_setfiles_mac(osbuild_t)