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) Change to the 'selinux' directory created when you expanded the
lsm-2.4-selinux-*.tgz archive (Download Option 1) or the selinux-*.tgz 
archive (Download Option 2 or 3).

2) 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.

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) Edit policy/file_contexts/{types.fc,program/*.fc} for your site.
Check the pathnames against your file system layout.  Some of the
pathnames found in types.fc or program/*.fc may not correspond to
actual pathnames that exist on your system.  You may wish to remove
these non-existent pathnames from these files, 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
no further changes are required.  If you want to run [xgk]dm, you will 
need a modified [xgk]dm program.  More information about using an X server 
or [xgk]dm with SELinux is in step 4 of the step-by-step INSTALLING 
instructions below.

6) 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 -
	   Enable different security models
	   Socket and Networking Security Hooks
	   Capabilities Support
	   NSA SELinux Support
	   NSA SELinux Development Support

    There are also several experimental SELinux options (MLS policy, 
    extended socket calls, labeled networking) that are not enabled by
    default.  You should only enable these options if you want to
    experiment with these features.  Read the help text associated
    with each option prior to enabling it.  If you choose to enable 
    the MLS policy option, then you should also read the README.MLS
    file.

7) Go to step 15 of the step-by-step INSTALLING instructions below.


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

BUILDING
--------

Change to the 'selinux' directory created when you expanded the
lsm-2.4-selinux-*.tgz archive (Download Option 1) or the selinux-*.tgz 
archive (Download Option 2 or 3).

You must 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.  
First, apply a SELinux-specific patch to these sources as follows:
    cd module
    make insert (or make insert LSMVER=-2.5)

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 -
		   Enable different security models
		   Socket and Networking Security Hooks
		   Capabilities Support
		   NSA SELinux Support
		   NSA SELinux Development Support
	 There are also several experimental SELinux options (MLS policy, 
	 extended socket calls, labeled networking) that are not enabled by
	 default.  You should only enable these options if you want to
	 experiment with these features.  Read the help text associated
	 with each option prior to enabling it.  If you choose to enable 
	 the MLS policy option, then you should also read the README.MLS
	 file.)
    make dep
    make
    make modules

INSTALLING
----------

0) Change to the 'selinux' directory created when you expanded the
lsm-2.4-selinux-*.tgz archive (Download Option 1) or the selinux-*.tgz 
archive (Download Option 2 or 3).

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 are experimental patches
for gdm and kdm by users of SELinux (discussed further below).  Consequently,
you should not enable an X Display Manager when running SELinux unless you
have separately obtained and installed these modified programs.

Domains have been defined for the X server, and we have successfully
run X via startx after a normal login.  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).  There is also a patch for kdm created by the
Debian selinux maintainer that is available from him.  You can use the 
modified gdm or kdm with the xdm_t domain defined in the example policy 
configuration.  

5) If installing tool packages (see Step 9), install any policy 
additions these tools might have:
   cd tools
   make insert-policy
   cd ..

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

8) Build and install the modified applications.

   cd utils
   make
   su (if not already root)
   make install
   cd ..
   
9) Build and install the tool packages included in the distribution. 
This step is optional, and should only be performed if you also 
performed step 5 above.  Some of these packages may also have 
additional installation procedures or warnings.  See 
tools/README for more information:

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

10) 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 ..

11) Copy the example files from utils/appconfig into /etc/security.
Each file is described below.

The default_contexts file defines 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.  Each line of the
default_contexts file specifies an entry consisting of a "partial
context" for the system process followed by a list of one or more
"partial contexts" for users in the desired prioritization order.  A
"partial context" is a context without a user identity value.  Partial
contexts are used in the list of user contexts since the user identity
can be inferred (it is the user who was authenticated or whose crontab
file was read).  Partial contexts are used for the system process
context to support future use by user-executed programs, like newrole,
where the user identity will also be inferred.  In the simplest form,
an entry identifies the system process context and then provides a
single user context to use as the default.

In the example default_contexts file, login and ssh sessions default
to user_r:user_t.  Users can then use newrole to change to a different
role.  System cron jobs default to system_r:system_crond_t, while user
cron jobs default to user_r:user_crond_t.  A derived domain
(user_crond_t) is used so that the policy can grant different
permissions to user cron jobs than to user sessions.

Each user can also have a $HOME/.default_contexts file that specifies
their own preferred default contexts.  However, only contexts for which
the user is authorized will be used.

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 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.

The passwd_context and shadow_context files define the context to be assigned
to the /etc/passwd and /etc/shadow files.  These files are used by the
spasswd collection of utilities to relabel /etc/passwd and /etc/shadow
after updating these two files so that they retain the correct context.

12) 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

13) Edit policy/file_contexts/{types.fc,program/*.fc} for your site.
Check the pathnames against your file system layout.  Some of the
pathnames found in types.fc or program/*.fc may not correspond to
actual pathnames that exist on your system.  You may wish to remove
these non-existent pathnames from these files, but no harm is done by
leaving them.

14) Install setfiles:
   cd setfiles
   make
   su (if not already root)
   make install
   cd ..
  
   Initialize or reset the persistent label mappings:
   cd policy
   make reset
   cd ..

15) 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.20-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.20-selinux, or you can directly run grubby, e.g. /sbin/grubby
--add-kernel=/boot/vmlinuz-2.4.20-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.

16) Boot the SELinux kernel.

17) 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.

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

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

20) 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
policy/file_contexts/{types.fc,program/*.fc} 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.

21) 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.

22) If the SELinux Development Support option was enabled in the kernel
configuration, then SELinux is built with development support.  With
this option, SELinux 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
specify "enforcing=1" on the kernel command line to start in enforcing
mode at boot time, 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 Support 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 'dontaudit' rule.

23) 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 under
policy/file_contexts and do a 'make relabel' 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.

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

25) 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.
