root/trunk/README

1) Reference Policy make targets:

General Make targets:

install-src             Install the policy sources into
                        /etc/selinux/NAME/src/policy, where NAME is defined in
                        the Makefile.  If not defined, the TYPE, as defined in
                        the Makefile, is used.  The default NAME is refpolicy.
                        A pre-existing source policy will be moved to
                        /etc/selinux/NAME/src/policy.bak.

conf                    Regenerate policy.xml, and update/create modules.conf
                        and booleans.conf.  This should be done after adding
                        or removing modules, or after running the bare target.
                        If the configuration files exist, their settings will
                        be preserved.  This must be ran on policy sources that
                        are checked out from the CVS repository before they can
                        be used.

clean                   Delete all temporary files, compiled policies,
                        and file_contexts.  Configuration files are left intact.

bare                    Do the clean make target and also delete configuration
                        files, web page documentation, and policy.xml.

html                    Regenerate policy.xml and create web page documentation
                        in the doc/html directory.

Make targets specific to modular (loadable modules) policies:

base                    Compile and package the base module.  This is the
                        default target for modular policies.

modules                 Compile and package all Reference Policy modules
                        configured to be built as loadable modules.

MODULENAME.pp           Compile and package the MODULENAME Reference Policy
                        module.

all                     Compile and package the base module and all Reference
                        Policy modules configured to be built as loadable
                        modules.

install                 Compile, package, and install the base module and
                        Reference Policy modules configured to be built as
                        loadable modules.

load                    Compile, package, and install the base module and
                        Reference Policy modules configured to be built as
                        loadable modules, then insert them into the module
                        store.

validate                Validate if the configured modules can successfully
                        link and expand.

install-headers         Install the policy headers into /usr/share/selinux/NAME.
                        The headers are sufficient for building a policy
                        module locally, without requiring the complete
                        Reference Policy sources.  The build.conf settings
                        for this policy configuration should be set before
                        using this target.

Make targets specific to monolithic policies:

policy                  Compile a policy locally for development and testing.
                        This is the default target for monolithic policies.

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 the labels on the filesystem, and report when
                        a file would be relabeled, but do not change its label.

restorelabels           Relabel the filesystem and report each file that is
                        relabeled.


2) Reference Policy Build Options (build.conf)

TYPE                    String.  Available options are standard, mls, and mcs.
                        For a type enforcement only system, set standard.
                        This optionally enables multi-level security (MLS) or
                        multi-category security (MCS) features.  This option
                        controls enable_mls, and enable_mcs policy blocks.

NAME                    String (optional).  Sets the name of the policy; the
                        NAME is used when installing files to e.g.,
                        /etc/selinux/NAME and /usr/share/selinux/NAME.  If not
                        set, the policy type (TYPE) is used.

DISTRO                  String (optional).  Enable distribution-specific policy.
                        Available options are redhat, rhel4, gentoo, debian,
                        and suse.  This option controls distro_redhat,
                        distro_rhel4, distro_gentoo, distro_debian, and
                        distro_suse policy blocks.

MONOLITHIC              Boolean.  If set, a monolithic policy is built,
                        otherwise a modular policy is built.

DIRECT_INITRC           Boolean.  If set, sysadm will be allowed to directly
                        run init scripts, instead of requiring the run_init
                        tool.  This is a build option instead of a tunable since
                        role transitions do not work in conditional policy.
                        This option controls direct_sysadm_daemon policy
                        blocks.

OUTPUT_POLICY           Integer.  Set the version of the policy created when
                        building a monolithic policy.  This option has no effect
                        on modular policy.

UNK_PERMS               String.  Set the kernel behavior for handling of
                        permissions defined in the kernel but missing from the
                        policy.  The permissions can either be allowed, denied,
                        or the policy loading can be rejected.

UBAC                    Boolean.  If set, the SELinux user will be used
                        additionally for approximate role separation.

MLS_SENS                Integer.  Set the number of sensitivities in the MLS
                        policy.  Ignored on standard and MCS policies.

MLS_CATS                Integer.  Set the number of categories in the MLS
                        policy.  Ignored on standard and MCS policies.

MCS_CATS                Integer.  Set the number of categories in the MCS
                        policy.  Ignored on standard and MLS policies.

QUIET                   Boolean.  If set, the build system will only display
                        status messages and error messages.  This option has no
                        effect on policy.


3) Reference Policy Files and Directories
All directories relative to the root of the Reference Policy sources directory.

Makefile                General rules for building the policy.

Rules.modular           Makefile rules specific to building loadable module
                        policies.

Rules.monolithic        Makefile rules specific to building monolithic policies.

build.conf              Options which influence the building of the policy,
                        such as the policy type and distribution.

config/appconfig-*      Application configuration files for all configurations
                        of the Reference Policy (targeted/strict with or without
                        MLS or MCS).  These are used by SELinux-aware programs.

config/local.users      The file read by load policy for adding SELinux users
                        to the policy on the fly.

doc/html/*              This contains the contents of the in-policy XML
                        documentation, presented in web page form.

doc/policy.dtd          The doc/policy.xml file is validated against this DTD.

doc/policy.xml          This file is generated/updated by the conf and html make
                        targets.  It contains the complete XML documentation
                        included in the policy.

doc/templates/*         Templates used for documentation web pages.

policy/booleans.conf    This file is generated/updated by the conf make target.
                        It contains the booleans in the policy, and their
                        default values.  If tunables are implemented as
                        booleans, tunables will also be included.  This file
                        will be installed as the /etc/selinux/NAME/booleans
                        file.

policy/constraints      This file defines additional constraints on permissions
                        in the form of boolean expressions that must be
                        satisfied in order for specified permissions to be
                        granted.  These constraints are used to further refine
                        the type enforcement rules and the role allow rules.
                        Typically, these constraints are used to restrict
                        changes in user identity or role to certain domains.

policy/global_booleans  This file defines all booleans that have a global scope,
                        their default value, and documentation.

policy/global_tunables  This file defines all tunables that have a global scope,
                        their default value, and documentation.

policy/flask/initial_sids  This file has declarations for each initial SID.

policy/flask/security_classes  This file has declarations for each security class.

policy/flask/access_vectors  This file defines the access vectors.  Common
                        prefixes for access vectors may be defined at the
                        beginning of the file.  After the common prefixes are
                        defined, an access vector may be defined for each
                        security class.

policy/mcs              The multi-category security (MCS) configuration.

policy/mls              The multi-level security (MLS) configuration.

policy/modules/*        Each directory represents a layer in Reference Policy
                        all of the modules are contained in one of these layers.

policy/modules.conf     This file contains a listing of available modules, and
                        how they will be used when building Reference Policy. To
                        prevent a module from  being used, set the module to
                        "off".  For monolithic policies, modules set to "base"
                        and "module" will be included in the policy.  For
                        modular policies, modules set to "base" will be included
                        in the base module; those set to "module" will be
                        compiled as individual loadable modules.

policy/rolemap          This file contains prefix and user domain type that
                        corresponds to each user role.  The contents of this
                        file will be used to expand the per-user domain
                        templates for each module.

policy/support/*        Support macros.

policy/users            This file defines the users included in the policy.

support/*               Tools used in the build process.


4) Building policy modules using Reference Policy headers:

The system must first have the Reference Policy headers installed, typically
by the distribution.  Otherwise, the headers can be installed using the
install-headers target from the full Reference Policy sources.

To set up a directory to build a local module, one must simply place a .te
file in a directory.  A sample Makefile to use in the directory is the
Makefile.example in the doc directory.  This may be installed in
/usr/share/doc, under the directory for the distribution's policy. 
Alternatively, the primary Makefile in the headers directory (typically
/usr/share/selinux/NAME/Makefile) can be called directly, using make's -f
option.

Larger projects can set up a structure of layers, just as in Reference
Policy, by creating policy/modules/LAYERNAME directories.  Each layer also
must have a metadata.xml file which is an XML file with a summary tag and
optional desc (long description) tag.  This should describe the purpose of
the layer.

Metadata.xml example:

<summary>ABC modules for the XYZ components.</summary>

Make targets for modules built from headers:

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                 Attempts to reinsert all modules that are currently
                        in the module store from the 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.