selinux-faq/en_US selinux-faq.xml,1.8,1.9

Author: csellers

Update of /cvs/docs/selinux-faq/en_US
In directory cvs-int.fedora.redhat.com:/tmp/cvs-serv26121

Modified Files:
	selinux-faq.xml 
Log Message:
fixed bugs in bz#18727, as well as added su/sudo from Proposed Additions


Index: selinux-faq.xml
===================================================================
RCS file: /cvs/docs/selinux-faq/en_US/selinux-faq.xml,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- selinux-faq.xml	13 Apr 2006 23:58:15 -0000	1.8
+++ selinux-faq.xml	19 Apr 2006 18:20:37 -0000	1.9
@@ -249,7 +249,7 @@
 		    files used in Reference Policy along with a Makefile and a
 		    small tool called <command>policygentool</command> used to
 		    generate a policy template file. The interface files reside
-		    in <filename>/usr/share/selinux/devel/headers</filename>
+		    in <filename>/usr/share/selinux/devel/include</filename>
 		    directory. If you want to see all of the policy files used
 		    to build the Reference Policy you need to install the
 		    src.rpm.
@@ -262,12 +262,34 @@

		<term><filename>selinux-policy-mls-<replaceable>&lt;version&gt;</replaceable>.noarch.rpm</filename></term>
 		<listitem>
 		  <para>
-		    Binary policy files are in
+		    Installed policy and supporting files are found in
+		    subdirectories of
 		   
<filename>/etc/selinux/<replaceable>policyname</replaceable>/</filename>.
-		    The policy for the types and domains is configured
-		    separately from security context for the subjects and
-		    objects.
+		    The subdirectories include
 		  </para>
+	          <itemizedlist>
+	            <listitem>
+	              <para>
+		        <filename>policy</filename> - binary policy that is
+		        loaded into the kernel
+	              </para>
+	            </listitem>
+	            <listitem>
+	              <para>
+		        <filename>contexts</filename> - context/labeling policy
+		        used for making labeling decisions by programs like
+			restorecon and fixfiles
+	              </para>
+	            </listitem>
+	            <listitem>
+	              <para>
+		        <filename>modules</filename> - store for policy modules
+		        that are combined to make the binary kernel policy.
+			Note that this should note be edited by hand, as it is
+			a private resource of libsemanage.
+	              </para>
+	            </listitem>
+		  </itemizedlist>
 		</listitem>
 	      </varlistentry>
 	    </variablelist>
@@ -601,15 +623,16 @@
           </question>
           <answer>
             <para>
-	      Prior to &FC; 5, SELinux policies were monolithic, meaning that
-	      they were compiled into a single policy binary. To make changes
-	      or additions to that policy, an administrator had to change out
-	      the entire policy. With &FC; 5, the policy is now modular. This
+	      Prior to &FC; 5, SELinux policies were monolithic, meaning making
+	      a change required getting the entire policy source, modifying it,
+	      compiling it, and replacing the current policy with it.
+	      With &FC; 5, the policy is now modular. This
 	      means that third party developers can ship policy modules with
 	      their applications, and then they can be added to the policy
-	      without having to switch out the entire policy in much the
-	      same way that kernel modules can add functionality to the kernel
-	      without having to reboot the entire system.
+	      without having to switch out the entire policy. The new module is
+	      then added to the module store, which results in a new policy
+	      binary that is a combination of the previous policy and the new
+	      module.
 	    </para>
 	    <para>
 	      This actually works by separating out compile and link steps
@@ -622,12 +645,23 @@
 	      The primary command for dealing with modules is
 	      <command>semodule</command>, which lets you perform basic
 	      functions such as installing, upgrading, or removing modules.
+	      Other useful commands include
+	      <command>checkmodule</command>, which is the module compiler
+	      and is installed with the checkpolicy rpm, as well as
+	      <command>semodule_package</command>, which creates a policy
+	      package file (.pp) from a compiled policy module.
+	    </para>
+	    <para>
 	      Modules are usually stored as policy package file (.pp
 	      extension) in
 	     
<filename>/usr/share/selinux/<replaceable>policyname</replaceable>/</filename>.
 	      There you should at least
 	      find the base.pp, which is the base module.
 	    </para>
+	    <para>
+	      To see how to write a simple policy module, check out
+	      <xref linkend="faq-entry-local.te"/>.
+	    </para>
           </answer>
         </qandaentry>
         <qandaentry id="faq-entry-whatis-managed-policy"
xreflabel="Managed Policy">
@@ -646,15 +680,20 @@
 	      easier. All policy management should use this library to access
 	      the policy store. The policy store holds all the policy
 	      information, and is found at
-	     
<filename>/etc/selinux/<replaceable>policyname</replaceable>/</filename>.
+	     
<filename>/etc/selinux/<replaceable>policyname</replaceable>/modules/</filename>.
 	    </para>
 	    <para>
 	      You should never have to edit the store directly. Instead, you
 	      should use tools that link against libsemanage. One example tool
 	      is <command>semanage</command>, which is a command line tool for
 	      managing much of the policy such as SELinux user mappings,
-	      SELinux port mappings, and file contexts entries. Other graphical
-	      tools are currently being developed as well.
+	      SELinux port mappings, and file contexts entries. Other examples
+	      of tools that use libsemanage include <command>semodule</command>
+	      which uses it to manage the SELinux policy modules installed to
+	      the policy store and <command>setsebool</command> which uses it
+	      manage SELinux policy booleans. Additionally, graphical
+	      tools are currently being developed to utilize the functionality
+	      provided by libsemanage.
 	    </para>
           </answer>
         </qandaentry>
@@ -678,6 +717,99 @@
         <qandaentry>
           <question>
             <para>
+	      I have some avc denials that I would like to allow, how do I do this?
+            </para>
+          </question>
+          <answer>
+            <para>
+	      If you have specific AVC messages you can use
+	      <command>audit2allow</command> to
+	      generate a Type Enforcement file that is ready to load as a policy
+	      module.
+            </para>
+<screen>
+<command>audit2allow -M local &lt; /tmp/avcs</command>
+</screen>
+	    <para>
+	      This creates a <filename>local.pp</filename> which you can
+	      then load into the kernel using
+	      <command>semodule -i local.pp</command>.
+	      You can also edit the <filename>local.te</filename> to make
+	      additional customizations. To create a module allowing all
+	      the denials since the last reboot that you can then customize,
+	      execute the following:
+	    </para>
+<screen>
+<command>audit2allow -m local -l -i /var/log/messages</command>
+</screen>
+	    <para>
+	      Note that the above assumes you are not using the audit daemon.
+	      If you were using the audit daemon, then you should use
+	      <filename>/var/log/audit/audit.log</filename> instead of
+	      <filename>/var/log/messages</filename> as your log file.
+	      This generates a <filename>local.te</filename> file, that
+	      looks similar to the following:
+	    </para>
+<screen>
+<computeroutput>module local 1.0;
+
+require {
+        class file { append execute execute_no_trans getattr ioctl read write };
+        type httpd_t;
+        type httpd_w3c_script_exec_t;
+ };
+
+
+allow httpd_t httpd_w3c_script_exec_t:file { execute execute_no_trans getattr ioctl read
};</computeroutput>
+</screen>
+	    <para>
+	      You can hand edit this file, removing allow statements that you
+	      don't want to allow, and then recompile and reload it
+	      using
+	    </para>
+	    <itemizedlist>
+	      <listitem>
+	        <para>
+	         <command>checkmodule -M -m -o local.mod local.te</command>
+		 to compile the te file. Note that
+		 <command>checkmodule</command> is part of the checkpolicy
+		 rpm, so you need to have it installed.
+	        </para>
+	      </listitem>
+	      <listitem>
+	        <para>
+	         <command>semodule_package -o local.pp -m local.mod</command>
+		 to create a policy package.
+	        </para>
+	      </listitem>
+	      <listitem>
+	        <para>
+	         <command>semodule -i local.pp</command> to add it to the
+		 current machine's running policy. This installs a new module
+		 called local with these rules into the module store.
+	        </para>
+	      </listitem>
+	    </itemizedlist>
+	    <note>
+	      <title>Important</title>
+	      <para>
+	        In order to load this newly created policy package into the
+		kernel, you are required to execute
+	        <command>semodule -i local.pp</command>
+	      </para>
+	      <para>
+		Note that
+		if you later install another module called local, it will
+		replace this module. If you want to keep these rules around,
+		then you either need to append future customizations to this
+		local.te, or give future customizations a different name.
+	      </para>
+	    </note>
+          </answer>
+        </qandaentry>
+        <qandaentry>
+          <question>
+            <para>
               How do I switch the policy I am currently using?
             </para>
           </question>
@@ -1121,96 +1253,137 @@
 </screen>
           </answer>
         </qandaentry>
-        <qandaentry>
+        <qandaentry id="faq-entry-local.te" xreflabel="Local Policy
Customizations">
           <question>
             <para>
 	      In the past I have written local.te file in policy sources for my
-	      own local customization to policy, how do I do this with
-	      Reference Policy?
+	      own local customization to policy, how do I do this
+	      in &FC; 5?
             </para>
           </question>
-          <answer>
-            <para>
-	      If you have specific AVC messages you can use
-	      <command>audit2allow</command> to
-	      generate a Type Enforcement file that is ready to load as a policy
-	      module.
-            </para>
-<screen>
-<command>audit2allow -M local &lt; /tmp/avcs</command>
-</screen>
+	  <answer>
 	    <para>
-	      This creates a <filename>local.pp</filename> which you can
-	      then load into the kernel using
-	      <command>semodule -i local.pp</command>.
-	      You can also edit the <filename>local.te</filename> to make
-	      additional customizations.
+	      Since &FC; 5 uses a modular policy, you don't have to have the
+	      complete policy source any more. Now, you can just create a local
+	      policy module for your local policy customizations. To do this,
+	      follow these steps.
 	    </para>
+	    <procedure>
+	      <step>
+		<para>
+	          Create a temporary directory, and change into it.
+	        </para>
 <screen>
-<computeroutput>audit2allow -M local -l -i /var/log/messages
-Generating type enforcement file: local.te
-Compiling policy
-checkmodule -M -m -o local.mod local.te
-semodule_package -o local.pp -m local.mod
-
-******************** IMPORTANT ***********************
-
-In order to load this newly created policy package into the kernel,
-you are required to execute
-
-semodule -i local.pp</computeroutput>
+<computeroutput>$ mkdir foo
+$ cd foo</computeroutput>
 </screen>
-	    <para>
-	      Note that the above assumes you are not using the audit daemon.
-	      If you were using the audit daemon, then you should use
-	      <filename>/var/log/audit/audit.log</filename> instead of
-	      <filename>/var/log/messages</filename> as your log file.
-	      This generates a <filename>local.te</filename> file, that
-	      looks similar to the following:
-	    </para>
+	      </step>
+	      <step>
+	        <para>
+		  Create empty te, if, and fc files.
+		</para>
 <screen>
-<computeroutput>module local 1.0;
+<computeroutput>$ touch local.te local.if local.fc</computeroutput>
+</screen>
+	      </step>
+	      <step>
+	        <para>
+		  Edit the local.te file, adding appropriate content.
+		  For example:
+		</para>
+<screen>
+<computeroutput>policy_module(local, 1.0)
 
 require {
-        class file { append execute execute_no_trans getattr ioctl read write };
-        type httpd_t;
-        type httpd_w3c_script_exec_t;
- };
+	attribute httpdcontent;
+	type smbd_t;
+}
 
-
-allow httpd_t httpd_w3c_script_exec_t:file { execute execute_no_trans getattr ioctl read
};</computeroutput>
+allow smbd_t httpdcontent:dir create_dir_perms;
+allow smbd_t httpdcontent:{ file lnk_file } create_file_perms;</computeroutput>
 </screen>
-	    <para>
-	      You can hand edit this file and then recompile and reload it
-	      using
-	    </para>
-	    <itemizedlist>
-	      <listitem>
 	        <para>
-	         <command>checkmodule</command> to compile the te file
-	        </para>
-	      </listitem>
-	      <listitem>
+		  There are 3 parts to this file.
+		</para>
+	        <itemizedlist>
+	          <listitem>
+	            <para>
+		      The <computeroutput>policy_module</computeroutput> call
+		      inserts statements to make the module work, including
+		      declaring the module and requiring system roles, classes,
+		      and permissions. Make sure the name declared here (local
+		      in this case) matches the name you gave the file
+		      (local.te).
+		    </para>
+	          </listitem>
+	          <listitem>
+	            <para>
+		      The <computeroutput>require</computeroutput> block
+		      lists the symbols that this module uses that must be
+		      declared in other modules. In this case, we require the
+		      attribute <computeroutput>httpdcontent</computeroutput>
+		      and the type <computeroutput>smbd_t</computeroutput>.
+		      Note that all types and attributes you use in rules
+		      must be required here unless you are declaring them
+		      yourself below.
+		    </para>
+	          </listitem>
+	          <listitem>
+	            <para>
+		      The rest of the file is the policy, in this case
+		      consisting only of a couple of allow rules. You could
+		      also place type declarations, dontaudit statements,
+		      interface calls, or most things that can go in a normal
+		      te file here.
+		    </para>
+	          </listitem>
+	        </itemizedlist>
+	      </step>
+	      <step>
 	        <para>
-	         <command>semodule_package</command> to create a policy package
-	        </para>
-	      </listitem>
-	      <listitem>
+		  Build the policy module.
+		</para>
+<screen>
+<computeroutput>$ make -f /usr/share/selinux/devel/Makefile
+Compliling targeted local module
+/usr/bin/checkmodule:  loading policy configuration from tmp/local.tmp
+/usr/bin/checkmodule:  policy configuration loaded
+/usr/bin/checkmodule:  writing binary representation (version 5) to tmp/local.mod
+Creating targeted local.pp policy package
+rm tmp/local.mod.fc tmp/local.mod</computeroutput>
+</screen>
+                <para>
+		  Note that this uses <command>checkmodule</command>, which is
+		  part of the checkpolicy rpm. So, make sure you install this
+		  rpm before doing this.
+		</para>
+	      </step>
+	      <step>
 	        <para>
-	         <command>semodule</command> to add it to the current machines
running policy
-	        </para>
-	      </listitem>
-	    </itemizedlist>
+		  Become root, and install the policy module with
+		  <command>semodule</command>.
+		</para>
+<screen>
+<computeroutput>$ su
+Password:
+# semodule -i local.pp</computeroutput>
+</screen>
+	      </step>
+	    </procedure>
 	    <note>
-	      <title>Important</title>
+	      <title>Module are uniquely identified by name</title>
 	      <para>
-	        In order to load this newly created policy package into the
-		kernel, you are required to execute
-	        <command>semodule -i local.pp</command>
+	        This means that if you later insert another
+		<filename>local.pp</filename>, it will
+		replace the one you just loaded. So, you should keep this
+		<filename>local.te</filename> around, and just add to it if you
+		need to make later policy customizations. If you lose it, but
+		want to keep your previous policy around, just call the new
+		local policy module something else (say local2.te).
 	      </para>
 	    </note>
-          </answer>
-        </qandaentry>
+	  </answer>
+	</qandaentry>
 	<qandaentry>
 	  <question>
 	    <para>
@@ -1441,35 +1614,32 @@
             </para>
           </answer>
         </qandaentry>
-<!--        <qandaentry>
+        <qandaentry>
           <question>
             <para>
-              All of the other &SEL; documentation states that the
-              <command>su</command> command will only change Linux identity
-              <emphasis>not</emphasis> security role.
+	      Does the <command>su</command> command change my SELinux
+	      identity and role?
             </para>
           </question>
           <answer>
             <para>
-              The &FC; development team has taken a slightly different direction
-              than existing &SEL; practice.  Security context transitions are
-              now integrated into <command>su</command> via
-              <computeroutput>pam_selinux</computeroutput>.  This greatly
-              simplifies using the system.
-            </para>
-            <para>
-              In practice, this is like combining the traditional
-              <command>su</command> with the &SEL;
<command>newrole</command>,
-              as one step instead of two.
+	      In previous versions of &FC;, security context transitions were
+              integrated into the <command>su</command> via
+              <computeroutput>pam_selinux</computeroutput>. This turned out
to
+	      be more trouble than it was worth, and is quite unnecessary on a
+	      system running targeted policy. So, this is no longer the case.
+	      Now, <command>su</command>/<command>sudo</command> only
change
+	      the Linux identy. You will need to use <command>newrole</command>
+	      to change the &SEL; identity, role, or level.
             </para>
             <para>
               Other forms of Linux/<trademark
                 class="registered">UNIX</trademark> identity change,
for example
-              <command>setuid(2)</command>, do not cause an &SEL;
identity
+              <command>setuid(2)</command>, also do not cause an &SEL;
identity
               change.
             </para>
           </answer>
-        </qandaentry> -->
+        </qandaentry>
         <qandaentry>
           <question>
             <para>
@@ -1845,9 +2015,9 @@
 	      Also, since the &FC; &LOCALVER; policy is based on the <xref
 		linkend="faq-entry-whatis-refpolicy"/>, you should look at the
 	      documentation on its project page. Another excellent source of
-	      information is the policy files in
+	      information is the example policy files in
 	     
<filename>/usr/share/doc/selinux-policy-<replaceable>&gt;version&lt;</replaceable></filename>

-	      which shows examples of policy.
+	      and <filename>/usr/share/selinux/devel</filename>.
 	    </para>
 	    <para>
 	      If you want to create a new policy domain, you can look at the
@@ -2094,6 +2264,8 @@
 	    </para>
           </question>
           <answer>
+<!-- This was fixed before final release of FC5, so can probably be removed
+Leaving for now just in case it returns
 <screen>
 <computeroutput>genhomedircon:  Warning!  No support yet for expanding ROLE macros
in the /etc/selinux/mls/contexts/files/homedir_template file when using libsemanage. 
 genhomedircon:  You must manually update file_contexts.homedirs for any non-user_r users
(including root).</computeroutput>
@@ -2105,6 +2277,7 @@
 	      problem and have non standard SELinux role/user combinations.
 	      IE You are using some custom policy.
 	    </para>
+-->
 <screen>
 <computeroutput>restorecon reset /etc/modprobe.conf context
system_u:object_r:etc_runtime_t->system_u:object_r:modules_conf_t
 restorecon reset /etc/cups/ppd/homehp.ppd context
user_u:object_r:cupsd_etc_t->system_u:object_r:cupsd_rw_etc_t</computeroutput>
@@ -2212,18 +2385,28 @@
 	  <question>
 	    <para>
 	      I am writing an php script that needs to create temporary files in
-	      <filename>/tmp</filename> and then execute them, SELinux policy is
-	      preventing this. What should I do?
+	      <filename>/tmp</filename> and possibly execute them, SELinux
+	      policy is preventing this. What should I do?
 	    </para>
 	  </question>
 	  <answer>
 	    <para>
-	      You should avoid having system applications writing to the
+	      First, you should never allow a system service to execute
+	      anything it can write. This gives an attacker the ability to
+	      upload malicious code to the server and then execute it, which
+	      is something we want to prevent.
+	    </para>
+	    <para>
+	      If you merely need to allow your script to create tempory
+	      (non-executable) files, this is possible. That said,
+	      you should avoid having system applications writing to the
 	      <filename>/tmp</filename> directory, since users tend to use the
 	      <filename>/tmp</filename> directory also. It would be better to
 	      create a directory elsewhere which could be owned by the apache
 	      process and allow your script to write to it. You should label the
-	      directory <computeroutput>httpd_sys_script_rw_t</computeroutput>.
+	      directory <computeroutput>httpd_sys_script_rw_t</computeroutput>,
+	      which will allow apache to write the temporary files to that
+	      directory.
 	    </para>
 	  </answer>
 	</qandaentry>
@@ -2311,7 +2494,8 @@
 	      In &FC; 5, the audit daemon is not installed by default, and
 	      consequently these messages can be found in
 	      <filename>/var/log/messages</filename> unless you choose to
-	      install the audit daemon, in which case AVC messages will be in
+	      install and enable the audit daemon, in which case AVC
+	      messages will be in
 	      <filename>/var/log/audit/audit.log</filename>.
             </para>
           </answer>