Split README to separate documents.

Use old wiki home page as new README.

Signed-off-by: Chris PeBenito <pebenito@ieee.org>

Author: pebenito

AGENTS.md

@@ -4,15 +4,7 @@ Guidance for automated coding agents working in the SELinux Reference Policy rep
 
 ## Repository Layout
 
-- `policy/modules/` contains policy modules grouped by layer. A module commonly has a
-  type-enforcement (`.te`), interface (`.if`), and file-context (`.fc`) file.
-- `policy/support/` contains shared policy macros and definitions.
-- `policy/` also contains users, constraints, capabilities, booleans, tunables, and Flask
-  definitions.
-- `config/appconfig-*` contains SELinux-aware application configuration for each policy type.
-- `support/` contains Python, shell, awk, and m4 build tools.
-- `testing/` contains standalone validation tools and testing configurations.
-- `doc/` contains project guides, example policy files, and documentation build sources.
+See `doc/REPO_LAYOUT.md` for repository paths and generated-file descriptions.
 
 ## Documentation
 
@@ -23,8 +15,8 @@ Guidance for automated coding agents working in the SELinux Reference Policy rep
   SELinux Notebook as the next reference when this repository does not answer the question.
 - If the SELinux Notebook does not answer the question, consult the upstream SELinux userspace
   man pages under `https://github.com/SELinuxProject/selinux/*/man/**` for further information.
-- Read `README.md` for make targets, build options, repository paths, and header-based module
-  builds.
+- Read `README.md` for the project overview and goals.
+- Read `doc/BUILD_INSTALL.md` for make targets, build options, and header-based module builds.
 - Read `doc/GETTING_STARTED.md` for the module structure and development workflow.
 - Follow `doc/STYLE_GUIDE.md` for ordering declarations, local rules, interfaces, and
   file-context entries.

README.md

@@ -1,155 +1,81 @@
 # SELinux Reference Policy
 
-## Make Targets
-
-### General Targets
-
-- **`install-src`**: Install policy sources into `/etc/selinux/NAME/src/policy`, where `NAME` is
-  defined in the Makefile. If unset, `TYPE` is used. The default `NAME` is `refpolicy`. A
-  pre-existing source policy is moved to `/etc/selinux/NAME/src/policy.bak`.
-- **`conf`**: Regenerate `policy.xml` and update or create `modules.conf` and `booleans.conf`. Run
-  this after adding or removing modules, or after running `bare`. Existing configuration settings
-  are preserved. This must be run on policy sources checked out from the CVS repository before
-  they can be used.
-- **`clean`**: Delete temporary files, compiled policies, and `file_contexts`. Configuration files
-  are left intact.
-- **`bare`**: Run `clean` and also delete configuration files, web documentation, and `policy.xml`.
-- **`html`**: Regenerate `policy.xml` and create web documentation in `doc/html`.
-
-### Modular Policy Targets
-
-- **`base`**: Compile and package the base module. This is the default modular policy target.
-- **`modules`**: Compile and package all Reference Policy modules configured as loadable modules.
-- **`MODULENAME.pp`**: Compile and package the `MODULENAME` Reference Policy module.
-- **`all`**: Compile and package the base module and all modules configured as loadable modules.
-- **`install`**: Compile, package, and install the base module and modules configured as loadable
-  modules.
-- **`load`**: Compile, package, and install the base module and loadable modules, then insert them
-  into the module store.
-- **`validate`**: Validate that the configured modules can successfully link and expand.
-- **`install-headers`**: Install policy headers into `/usr/share/selinux/NAME`. The headers are
-  sufficient for building a policy module locally without the complete Reference Policy sources.
-  Set the `build.conf` options for this policy configuration before using this target.
-- **`build-interface-db`**: Build the policy interface database with `sepolgen-ifgen`. This is
-  required for reference-style policy generation by `audit2allow --reference`.
-
-### Monolithic Policy Targets
-
-- **`policy`**: Compile a policy locally for development and testing. This is the default
-  monolithic policy target.
-- **`install`**: Compile and install the policy and file contexts.
-- **`load`**: Compile and install the policy and file contexts, then load the policy.
-- **`enableaudit`**: Remove all `dontaudit` rules from `policy.conf`.
-- **`relabel`**: Relabel the filesystem.
-- **`checklabels`**: Check filesystem labels and report when a file would be relabeled without
-  changing its label.
-- **`restorelabels`**: Relabel the filesystem and report each file that is relabeled.
-
-## Build Options
-
-The following options are set in `build.conf`.
-
-- **`TYPE`** (`String`): Available options are `standard`, `mls`, and `mcs`. For a
-  type-enforcement-only system, use `standard`. This optionally enables multi-level security
-  (MLS) or multi-category security (MCS) features and controls `enable_mls` and `enable_mcs`
-  policy blocks.
-- **`NAME`** (`String`, optional): Set the policy name used when installing files under paths such
-  as `/etc/selinux/NAME` and `/usr/share/selinux/NAME`. If unset, the policy `TYPE` is used.
-- **`DISTRO`** (`String`, optional): Enable distribution-specific policy. Available options are
-  `redhat`, `gentoo`, and `debian`. This controls the `distro_redhat`, `distro_gentoo`, and
-  `distro_debian` build-option policy blocks.
-- **`MONOLITHIC`** (`Boolean`): Build a monolithic policy when set; otherwise, build a modular
-  policy.
-- **`DIRECT_INITRC`** (`Boolean`): Allow `sysadm` to run init scripts directly instead of using
-  `run_init`. This is a build option rather than a tunable because role transitions do not work in
-  conditional policy. It controls `direct_sysadm_daemon` policy blocks.
-- **`OUTPUT_POLICY`** (`Integer`): Set the policy version created by a monolithic build. This has
-  no effect on modular policy.
-- **`OUTPUT_MODULE`** (`Integer`): Set the module policy version created by a modular build. This
-  has no effect on monolithic policy.
-- **`UNK_PERMS`** (`String`): Set kernel behavior for permissions defined in the kernel but missing
-  from the policy. Permissions can be allowed (`allow`), denied (`deny`), or cause policy loading
-  to be rejected (`reject`).
-- **`UBAC`** (`Boolean`): Also use the SELinux user for approximate role separation.
-- **`SYSTEMD`** (`Boolean`): Assume systemd is the init process provider.
-- **`MLS_SENS`** (`Integer`): Set the number of MLS sensitivities. Ignored for standard and MCS
-  policies.
-- **`MLS_CATS`** (`Integer`): Set the number of MLS categories. Ignored for standard and MCS
-  policies.
-- **`MCS_CATS`** (`Integer`): Set the number of MCS categories. Ignored for standard and MLS
-  policies.
-- **`QUIET`** (`Boolean`): Display only status and error messages. This has no effect on policy.
-- **`WERROR`** (`Boolean`): Treat warnings as errors. The build fails if warnings are encountered.
-
-## Files and Directories
-
-All paths are relative to the root of the Reference Policy source directory.
-
-- **`Makefile`**: General rules for building the policy.
-- **`Rules.modular`**: Makefile rules for building loadable module policies.
-- **`Rules.monolithic`**: Makefile rules for building monolithic policies.
-- **`build.conf`**: Options that influence the policy build, such as policy type and distribution.
-- **`config/appconfig-*`**: Application configuration files for all Reference Policy
-  configurations, including targeted or strict policy with or without MLS or MCS. SELinux-aware
-  programs use these files.
-- **`config/local.users`**: File read when loading policy to add SELinux users to the policy.
-- **`doc/html/*`**: In-policy XML documentation presented as web pages.
-- **`doc/policy.dtd`**: DTD used to validate `doc/policy.xml`.
-- **`doc/policy.xml`**: File generated or updated by `conf` and `html`. It contains the complete XML
-  documentation included in the policy.
-- **`doc/templates/*`**: Templates used for documentation web pages.
-- **`policy/booleans.conf`**: File generated or updated by `conf`. It contains policy booleans and
-  their default values. If tunables are implemented as booleans, tunables are also included. This
-  is installed as `/etc/selinux/NAME/booleans`.
-- **`policy/constraints`**: Additional constraints on permissions, expressed as Boolean
-  expressions that must be satisfied for permissions to be granted. These constraints further
-  refine type-enforcement and role-allow rules and typically restrict user identity or role
-  changes to certain domains.
-- **`policy/global_booleans`**: Global booleans, their default values, and documentation.
-- **`policy/global_tunables`**: Global tunables, their default values, and documentation.
-- **`policy/flask/initial_sids`**: Declarations for each initial SID.
-- **`policy/flask/security_classes`**: Declarations for each security class.
-- **`policy/flask/access_vectors`**: Access-vector definitions. Common prefixes may be defined at
-  the beginning of the file, followed by an access vector for each security class.
-- **`policy/mcs`**: Multi-category security (MCS) configuration.
-- **`policy/mls`**: Multi-level security (MLS) configuration.
-- **`policy/modules/*`**: Layer directories containing all Reference Policy modules.
-- **`policy/modules.conf`**: Available modules and how they are used when building Reference
-  Policy. Set a module to `off` to omit it. For monolithic policies, modules set to `base` or
-  `module` are included. For modular policies, modules set to `base` are included in the base
-  module and those set to `module` are compiled as individual loadable modules.
-- **`policy/support/*`**: Support macros.
-- **`policy/users`**: Users included in the policy.
-- **`support/*`**: Tools used in the build process.
-
-## Building Modules Using Reference Policy Headers
-
-The system must first have the Reference Policy headers installed, typically by the distribution.
-Otherwise, install the headers from the complete Reference Policy sources with the
-`install-headers` target.
-
-To build a local module, place a `.te` file in a directory. Use `doc/Makefile.example` as the
-Makefile. It may be installed under `/usr/share/doc` in the directory for the distribution's
-policy. Alternatively, call the primary Makefile in the headers directory, typically
-`/usr/share/selinux/NAME/Makefile`, directly with `make -f`.
-
-Larger projects can use layers like Reference Policy by creating `policy/modules/LAYERNAME`
-directories. Each layer must have a `metadata.xml` file containing a `summary` tag and an optional
-`desc` tag for a longer description. The metadata should describe the layer's purpose.
-
-Example `metadata.xml`:
-
-```xml
-<summary>ABC modules for the XYZ components.</summary>
-```
-
-### Header-Based Module Targets
-
-- **`MODULENAME.pp`**: Compile and package the `MODULENAME` local module.
-- **`all`**: Compile and package the modules in the current directory.
-- **`load`**: Compile and package the modules in the current directory, then insert them into the
-  module store.
-- **`refresh`**: Attempt to reinsert all modules currently in the module store from local and
-  system module packages.
-- **`xml`**: Build a `policy.xml` from the XML included with the base policy headers and any XML in
-  the modules in the current directory.
+The SELinux Reference Policy project (refpolicy) is a complete SELinux
+policy that can be used as the system policy for a variety of systems
+and used as the basis for creating other policies. Reference Policy was
+originally based on the NSA example policy, but aims to accomplish many
+additional goals.
+
+The current release of Reference Policy is available from the
+[GitHub releases](https://github.com/SELinuxProject/refpolicy/releases) page.
+
+The project is always looking for policy developers interested in
+contributing. See the [getting started guide](doc/GETTING_STARTED.md) for
+more information on writing Reference Policy modules.
+
+For an in-depth discussion of Reference Policy concepts, see the
+[paper](http://selinuxsymposium.org/2006/papers/05-refpol.pdf) published
+at the 2006 SELinux Symposium.
+
+## Project Goals
+
+Security is the reason for existence for SELinux policies and must,
+therefore, always be the first priority. The common view of security as
+a binary state (secure or not secure) is not a sufficient goal for
+developing an SELinux policy. In reality, different systems have
+different requirements and purposes and corresponding differences in the
+meaning of secure. What is a fundamental security flaw on one system
+might be acceptable, or even the primary functionality, of another. The
+challenge for a system policy is to support as many of these differing
+security goals as is practical. To accomplish this Reference Policy will
+provide:
+
+- **Strong Modularity**: central to the design of the policy is strict
+    modularity. Accesses to resources are abstracted, and implementation
+    details are encapsulated in the module.
+
+- **Security Goals**: clearly stated security goals will be given for each
+    component of the policy. This will allow policy developers to
+    determine if a given component meets their security needs.
+
+- **Documentation**: the difficulty and complexity of creating SELinux
+    policies has become the number one barrier to the adoption of
+    SELinux. It also potentially reduces the security of the policies: a
+    policy that is too complex to easily understand is difficult to make
+    secure. See the `doc/` directory of the repository for more information.
+
+- **Development Tool Support**: In addition to documentation,
+    Reference Policy aims to make improvements in this area, making
+    policies easier to develop, understand, analyze, and verify by
+    adding interface call backtraces which can be used for debugging and
+    graphical development tools.
+
+- **Forward Looking**: Reference Policy aims to support a variety of
+    policy configurations all from the same source tree. This is done
+    through the addition of infrastructure for automatically handling
+    the differences between monolithic and modular policies and the
+    additional MLS fields to all policy statements that include contexts.
+
+- **Configurability**: configuration tools that allow the policy
+    developer to make important security decisions including defining
+    roles, configuring networking.
+
+- **Flexible Base Policy**: a base policy that protects the basic
+    operating system and serves as a foundation to the rest of the
+    policy. This base policy should be able to support a variety of
+    application policies with differing security goals.
+
+- **Application Policy Variations**: application policy variations
+    that make different security tradeoffs. For example, two Apache
+    policies might be created, one that is for serving read-only static
+    content that is severely restricted, and another that is appropriate
+    for dynamic content.
+
+- **Multi-Level Security**: MLS is supported out-of-the-box without
+    requiring destructive changes to the policy. It is possible to
+    compile an MLS and non-MLS policy from the same policy files by
+    switching a configuration option.
+
+## Contributing
+
+If you'd like to contribute, please see [how to contribute](doc/HOW_TO_CONTRIBUTE.md).