QUICK INSTALL
-------------

If you want to install SELinux with a minimum of hassle, you can
follow these quick install instructions.  If you have a problem with
this quick install or you want to understand the installation
procedure thoroughly, then skip down to the BUILDING and INSTALLING
sections below for step-by-step instructions.

1) Make sure that you have a copy of the LSM-patched 2.4 kernel sources in
../lsm-2.4 or the LSM-patched 2.5 kernel sources in ../lsm-2.5.

2) Edit policy/users for your users.
This file defines each user recognized by the system security policy.
It specifies the authorized roles for each user.  Be sure to authorize
at least one user for the system administrator role (sysadm_r).  Other
users can be limited to the ordinary user role (user_r).  Remove the
example users provided in the distributed users file (jadmin and
jdoe).

3) Edit the default_context and cron_context files in utils/appconfig
for your users.  These files define default security contexts for user
login or ssh sessions and for user cron jobs.  A security context has
the syntax user:role:domain or user:role:type,
e.g. root:sysadm_r:sysadm_t or root:user_r:user_t.  Remove the example
users (jadmin and jdoe).  Be sure to leave the system_u user unchanged
in the cron_context file - this is needed for system cron jobs.  More
detail about these files is in the step-by-step instructions.

4) Edit setfiles/file_contexts for your site.  Check the pathnames
against your file system layout.  Some of the pathnames found in
policy/file_contexts may not correspond to actual pathnames that exist
on your system.  You may wish to remove these non-existent pathnames
from this file, but no harm is done by leaving them.

5) Ensure that your current configuration is not set up to run an X
Display Manager (xdm, gdm, kdm).  The default runlevel specified in
/etc/inittab should be runlevel 3 (Full multiuser mode), not runlevel
5 (X11).  If you want to run X via startx after a normal login, then
edit policy/domains/program/xserver.te and uncomment the lines
preceded by "# Commented out by default".  If you want to run gdm,
you will need a modified gdm program.  More information about
using an X server or gdm with SELinux is in step 4 of the step-by-step
INSTALLING instructions below.

6) If you are running RH7.1 rather than RH7.2, then first edit the
utils/Makefile, commenting out the LOGROTATE_VER definition for RH7.2 
and uncommenting the corresponding definition for RH7.1.

7) Perform the quick install:
   su
   make quickinstall (or make quickinstall LSMVER=-2.5)

   When the kernel configuration menu is displayed, configure the
   kernel for your hardware as appropriate.  In particular, be sure
   that the processor type is set correctly and that the driver for your 
   network card is enabled.  If you are using ext3 filesystems, be sure
   to enable the ext3 filesystem support.  Also, the following options should 
   be set by default from the patched defconfig file:  
	Networking Options -
	   Network Packet Filtering
	Security Options -
	   Capabilities Support
	   IP Networking Support
	   NSA SELinux Support
	   NSA SELinux Development Module

    If you want to experiment with the labeled networking support, then
    you should also enable the following Security Options:
	   Labeled IP Networking Support
	   CIPSO/FIPS188 IP Options
    However, keep in mind that this support is still considered experimental.

8) Go to step 13 of the step-by-step INSTALLING instructions below.


STEP-BY-STEP BUILDING AND INSTALLING
------------------------------------

BUILDING
--------

You must have a copy of the LSM-patched 2.4 kernel sources in ../lsm
or the LSM-patched 2.5 kernel sources in ../lsm-2.5.  
First, apply a patch to these sources as follows:
    cd module
    make insert (or make insert LSMVER=-2.5)
	(This will patch arch/i386/defconfig to provide appropriate
	 default Security option settings, and it will patch
         the top-level Makefile to use the -selinux suffix.)

Now, you can build the SELinux kernel:
    cd ../../lsm-2.4 (or cd ../../lsm-2.5)
    make menuconfig 
	(Configure for your hardware as appropriate.
	 In particular, be sure that the processor type is set correctly 
	 and that the driver for your network card is enabled.  If you
	 are using ext3 filesystems, be sure to enable ext3 filesystem
	 support.  Also, the following options should be set by default 
	 from the patched defconfig file:  
		Networking Options -
		   Network Packet Filtering
		Security Options -
		   Capabilities Support
		   IP Networking Support
		   NSA SELinux Support
		   NSA SELinux Development Module
	 If you want to experiment with the labeled networking support, then
	 you should also enable the following Security Options:
		   Labeled IP Networking Support
		   CIPSO/FIPS188 IP Options
	 However, keep in mind that this support is still considered experimental.)
    make dep
    make
    make modules

INSTALLING
----------

1) Install the SELinux kernel in the usual manner, e.g.:
    su
    cd ../lsm-2.4 (or cd ../lsm-2.5)
    make install
    make modules_install
    cd ../selinux

2) Install the support files from the SELinux module used to build the
remaining components:
   su
   cd module
   make install (or make install LSMVER=-2.5)
   cd ..

3) Edit policy/users for your users.

This file defines each user recognized by the system security policy.
It specifies the authorized roles for each user.  Be sure to authorize
at least one user for the system administrator role (sysadm_r).  Other
users can be limited to the ordinary user role (user_r).  Remove the
example users provided in the distributed users file (jadmin and
jdoe).

4) Ensure that your current configuration is not set up to run an X
Display Manager (xdm, gdm, kdm).  The default runlevel specified in
/etc/inittab should be runlevel 3 (Full multiuser mode), not runlevel
5 (X11).  We do not provide a modified xdm/gdm/kdm to set the security
context for the user session, although there is an experimental patch
for gdm by a user of SELinux (discussed further below).  Consequently,
you should not enable an X Display Manager when running SELinux.

Domains have been defined for the X server, and we have successfully
run X via startx after a normal login.  However, these domains require
certain permissions that are highly privileged.  The X server still
requires study to determine how to support it in a secure fashion.  To
run X, you will need to uncomment the allow statements preceded by
comment lines that say '# Commented out by default' in the
policy/domains/program/xserver.te file prior to building and
installing the policy.

If you truly need to run an X Display Manager, there is an
experimental patch for gdm created by a user of SELinux that is
available on the sourceforge selinux project site (not maintained by
us).  You can use that modified gdm with the xdm_t domain defined in the
example policy configuration.  As with the X domain, you will need to
uncomment the allow statements preceded by comment lines that say '#
Commented out by default' in the policy/domains/program/xdm.te file
prior to building and installing the policy.  

5) Build and install the example policy configuration:
   cd policy
   make 
   su (if not already root)
   make install
   cd ..
  
6) Build and install libsecure and its test programs:
   cd libsecure
   make
   su (if not already root)
   make install
   cd ..

7) If you want to experiment with the labeled networking support, then
   build and install the Selopt utilities:
   cd selopt
   make (or make LSMVER=-2.5)
   su (if not already root)
   make install
   cd ..

8) Build and install the modified applications.
   If you are running RH7.1, then first edit the utils/Makefile,
   commenting out the LOGROTATE_VER definition for RH7.2 and uncommenting 
   the corresponding definition for RH7.1.

   cd utils
   make
   su (if not already root)
   make install
   cd ..

9) Copy the example files from utils/appconfig into /etc/security
and edit them for your site.  Each file is described below.

The default_context file defines the default login security context
for each user.  A security context has the syntax user:role:domain or
user:role:type, e.g.  root:sysadm_r:sysadm_t or root:user_r:user_t.
This file is used by the modified login program and by the modified
sshd program.

The default_type file defines the default type (domain) for each role.
Each entry has the syntax role:domain, e.g. sysadm_r:sysadm_t
or user_r:user_t.  This file is used by the modified login program
and by the newrole program.

The cron_context file defines the security context used by the
modified crond for cron jobs.  This file also has the same format as
the default_context file.  An entry must be provided for the system
user (system_u), e.g.  system_u:system_r:system_crond_t.  This entry
is used for system cron jobs.  Regular users should use a derived
domain, e.g.  root:sysadm_r:sysadm_crond_t or
root:user_r:user_crond_t, so that the policy configuration can grant
different permissions to user cron jobs than to interactive user
sessions.

The initrc_context file defines the security context to be used when 
init scripts are started with the run_init command. The init scripts 
will be run in the given security context, but processes started by
the scripts may automatically enter other contexts based on the policy.
The run_init command allows administrators to securely run init scripts 
in the same context as the system startup.

We plan on eliminating the need for the default_context and cron_context 
configuration files in the future through the use of the 
security_get_user_sids system call.

10) If you have previously booted the non-LSM version of SELinux
on this system, then remove any existing persistent label mappings.
These mappings are stored in the ...security subdirectory in the root
directory of each file system.  For example, you might do:
	rm -rf /...security /boot/...security /home/...security

11) Edit setfiles/file_contexts for your site.  Check the pathnames
against your file system layout.  Some of the pathnames found in
policy/file_contexts may not correspond to actual pathnames that exist
on your system.  You may wish to remove these non-existent pathnames
from this file.  However, if you leave some of these non-existent
pathnames in this file, you will see warnings in the next step, but
the system will still operate correctly.

12) Set the file security contexts:
   cd setfiles
   make
   su (if not already root)
   make relabel
   cd ..

This will compile the setfiles utility program and run it on the
file_contexts configuration file to set the security contexts on the
files in your file system.  The setfiles utility program will work
correctly regardless of whether or not you are already running the
SELinux module on your system.  If you are already running the SELinux
module, the program will use the new system calls defined by the
module to update the file label mapping.  Otherwise, the program will
directly access the file label mapping, creating it if necessary.

13) Configure your boot manager to boot the SELinux kernel.  

If you use the LILO boot manager, you can accomplish this
configuration as follows: First, add an entry for the new kernel to
/etc/lilo.conf.  You can determine the name of the new kernel by
looking in /boot.  The new kernel's name will end in "-selinux"
(example: "vmlinuz-2.4.18-selinux").  Do not use an initrd= option
with the new entry.  Retain an entry for your original kernel so that
you can boot it from the lilo prompt if necessary.  Finally, run
/sbin/lilo.

If you are using GRUB with RH7.2, then you can either run RedHat's
/sbin/new-kernel-pkg script, e.g. /sbin/new-kernel-pkg --install
2.4.18-selinux, or you can directly run grubby, e.g. /sbin/grubby
--add-kernel=/boot/vmlinuz-2.4.18-selinux --copy-default
--make-default --title "SELinux".  Notice that /sbin/new-kernel-pkg
does NOT make the new kernel the default, whereas the example for
grubby uses the --make-default option to make it so.

14) Boot the SELinux kernel.

15) Login in the sysadm_r role and sysadm_t domain.
If you are logging into the console, you can interactively
specify a role and domain other than the entry in the
/etc/security/default_context file.  If you are logging
in remotely via sshd, sshd will use your default context
but you can change to another role via the newrole program.

16) Run setfiles again to ensure that files created by the
old kernel during the shutdown are properly labeled:
   cd setfiles
   su (if not already root)
   make verbose
   cd ..

17) Add /usr/local/selinux/bin and /usr/local/selinux/sbin
to your path for the modified utilities.

18) Try 'ps -e --context'.  The second column should show the security
context of each process.  As mentioned above, a security context has
the syntax user:role:domain or user:role:type.  

System processes should have the system_u user identity and the
system_r role.  Each system process with a different executable should
have its own separate domain.  If some system processes are running in
the initrc_t domain, then either we have not moved it into a separate
domain yet or the pathname for the executable in setfiles/file_contexts
is not correct.  You should either disable any system processes
left in the initrc_t domain (if you do not need them) or define
new domains for them.  

Your user processes should have your user identity and the sysadm_r
role.  Your shell and most of its children will have the sysadm_t
domain.  Some of the processes that you run may be in different
domains because they require different privileges.

19) Try 'ls --context /'.  The fourth column should show the security
context of each file or directory in /.  Initially, the system_u user
identity is used for all files at installation time.  When you create
new files after installation, they will be assigned the user identity
of the creating process.  The object_r role is used for all files,
because roles are not relevant for files.  Files with different
protection requirements will have different types, e.g. /boot has the
boot_t type and /etc has the etc_t type.

20) If the SELinux Development Module option was enabled in the kernel
configuration, then your SELinux module is a development module.  The
development module starts in permissive mode, logging permission
failures but not enforcing them.  You can use permissive mode in order
to determine what additional permissions are needed for your
particular system and can then revise your policy configuration
accordingly.  You can subseqently run the avc_toggle program to switch
into enforcing mode.  Once in enforcing mode, you can only switch back
to permissive mode if authorized by the policy (in the example policy,
only the sysadm_r role can do this).  Once you are satisfied that your
policy configuration is sufficient for your system, you should either
run avc_toggle from an rc script to switch into enforcing mode during
initialization, or you should rebuild the kernel without this option
so that it is always in enforcing mode.  The first option leaves open
the possibility of switching back to permissive mode by an
administrator, while the latter option provides stricter security.  If
you choose the latter option, be sure to keep a kernel that is built
with the Development Module option available for emergency recovery
(e.g. if you make an error in your policy configuration that renders
your system unuseable).

You may find the contributed scripts/newrules.pl script useful in
generating additional 'allow' rules from the log messages for your
policy, but the generated rules should be carefully reviewed to ensure
that they are consistent with your security goals.  You may find it
desirable to define new domains and/or types rather than simply
granting the permission for an existing domain and/or type in order to
preserve existing security guarantees.  You may also find that certain
permission denials require other kinds of policy changes, e.g. changes
to the RBAC or constraints configurations.  You may also find that
certain permission denials are not fatal to the application and you
may not want to grant these permissions due to your security goals.
In that case, you may wish to simply suppress logging of the denial
via an 'auditdeny' rule.

21) Experiment with the modified utilities and with customizing the
example policy configuration for your particular needs.  You can edit
the policy configuration in the policy directory and then run 'make
load' in that directory to load a new policy into a running SELinux
module (only from the sysadm_r role and sysadm_t domain if you are in
enforcing mode).  You can edit the file contexts configuration in
setfiles/file_contexts and do a 'make relabel' in that directory to
update your file security contexts.  You can also use the 'chcon'
program to change security contexts directly, but such changes will be
lost if you subsequently do a 'make relabel' unless you update your
file contexts configuration.

22) If you want to experiment with labeled networking support between
SELinux systems, then read selopt/README.SELinux.

23) If you subsequently reboot with a non-SELinux kernel, be sure to
run setfiles again before booting SELinux to reset your file security
contexts properly.


