Difference between revisions of "ConfigurationFiles"

From SELinux Wiki
Jump to: navigation, search
(SELinux Configuration Files)
 
Line 1: Line 1:
 
= SELinux Configuration Files =
 
= SELinux Configuration Files =
This section explains each SELinux configuration file with its format, example content and where applicable, any supporting SELinux command or library API function names where the appropriate man(3) pages should be consulted regarding their use).  
+
== Introduction ==
 +
This section explains each SELinux configuration file with its format, example content and where applicable, any supporting SELinux commands or libselinux library API function names.  
  
Note: Configuration file names and content have changed over the various releases of SELinux, this section defines those seen in the Fedora 12 release when building custom and Reference Policy policies.
+
Where configuration files have specific man pages, these are noted by adding the man page section (e.g. <tt>'''semanage.config'''(5)</tt>).
  
This Section classifies the types of configuration file used in SELinux as follows:
+
This Notebook classifies the types of configuration file used in SELinux as follows:
 +
* [[GlobalConfigurationFiles | Global Configuration Files]] that affect the active policy and their supporting SELinux-aware applications, utilities or commands. This Notebook will only refer to the commonly used configuration files.
 +
* [[PolicyConfigurationFiles | Policy Configuration Files]] used by an active (run time) policy and their supporting [[PolicyStoreConfigurationFiles | Policy Store Configuration Files]].
 +
: The Policy Store Configuration files are 'private'<ref name="ftn30"><sup>They should NOT be edited as together they describe the 'policy'.</sup></ref> and managed by the '''semanage'''(8) and '''semodule'''(8) commands<ref name="ftn31"><sup>The system-config-selinux GUI (supplied in the polycoreutils-gui rpm) can also be used to manage users, booleans and the general configuration of SELinux as it calls '''semanage'''(8), however it does not manage all that the semanage command can (it also gets bitter & twisted if there are no MCS/MLS labels on some operations).</sup></ref>. These are used to build the majority of the [[PolicyConfigurationFiles | Policy Configuration Files]]. This store will be moving as part of a migration programme, see [https://github.com/SELinuxProject/selinux/wiki/Policy-Store-Migration https://github.com/SELinuxProject/selinux/wiki/Policy-Store-Migration] and [[#Policy Store Migration | Policy Store Migration]] for details.
 +
: Note there can be multiple policy configuration areas on a system (e.g. <tt>/etc/selinux/targeted</tt> and <tt>/etc/selinux/mls</tt>), however only one can be the active policy).
 +
* [[NB_LSM#SELinux_Filesystem | SELinux Kernel Configuration files]] located under the <tt>/sys/fs/selinux</tt> directory and reflect the current configuration of SELinux for the active policy. This area is used extensively by the libselinux library for userspace object managers and other SELinux-aware applications. These files and directories should not be updated by users (the majority are read only anyway), however they can be read to check various configuration parameters.
  
* Global Configuration files that affect the active policy and their supporting SELinux-aware applications, utilities or commands. These can be located in <tt>/etc/selinux</tt> or other places depending on the application.
+
=== Policy Store Migration ===
* Files specific to a named policy configuration that are located at <tt>/etc/selinux/<policy_name></tt>, where <tt><policy_name></tt> is the name given in the <tt>SELINUXTYPE=</tt> entry of the <tt>/etc/selinux/config</tt> file. The files in this area are split into two main sections:
+
When distributions move to version 2.4 of <tt>libsemanage</tt>, <tt>libsepol</tt>, and <tt>policycoreutils</tt> the policy module store will move from <tt><nowiki>/etc/selinux/<SELINUXTYPE>/modules</nowiki></tt> to <tt><nowiki>/var/lib/selinux/<</nowiki>SELINUXTYPE></tt>. Once the libraries are upgraded, all policy stores must be migrated before any commands can be executed that modify or use the store, for example <tt>'''semodule'''(8)</tt> or <tt>'''semanage'''(8)</tt>. See [https://github.com/SELinuxProject/selinux/wiki/Policy-Store-Migration https://github.com/SELinuxProject/selinux/wiki/Policy-Store-Migration] for details.
** The Policy Store Configuration files that are 'private'<ref name="ref1">They should NOT be edited as together they describe the 'policy'.</ref> and managed by the <tt>semanage(8)</tt> and <tt>semodule(8)</tt> commands<ref name="ref2">The <tt>system-config-selinux</tt> GUI (supplied in the polycoreutils-gui rpm) can also be used to manage users, booleans and the general configuration of SELinux as it calls semanage, however it does not manage all that the semanage command can (it also gets bitter & twisted if there are no MCS/MLS labels on some operations).</ref>. These are located in the <tt>/etc/selinux/<policy_name>/module</tt> set of directories. These are used to build the majority of the Policy Configuration files.
+
** The Policy Configuration files that are used when the policy is activated<ref name="ref3">The 'active policy' is pointed to by an entry in the <tt>/etc/selinux/config</tt> file discussed in the <tt>/etc/selinux/config</tt> file section.</ref>. The majority of these files are now managed via the Policy Store and should not be edited directly, however others are specific to SELinux-aware applications and have no configuration utilities (e.g. debus and X-Windows context files).
+
* SELinux Kernel Configuration files that are located under the <tt>/selinux</tt> directory and reflect the current configuration of SELinux and the active policy. This area is used extensively by the <tt>libselinux</tt> library for user space object managers and other SELinux-aware applications. These files and directories should not be updated by users (the majority are read only anyway), however they can be read to check various configuration parameters. ToDO - Put in link to these when I've done them.
+
  
Whenever possible the appropriate SELinux application should be used to manage all of these configuration files.
+
Once the migration is complete:
 +
* The policy store configuration files will no longer be available.
 +
* It will be possible to build policies containing a mixture of Reference Policy modules, kernel policy language modules and modules written in the CIL language as shown in the following example:
 +
<pre>
 +
# Compile and install a base and two modules written in kernel language:
 +
checkmodule -o base.mod base.conf
 +
semodule_package -o base.pp -m base.mod -f base.fc
 +
checkmodule -m ext_gateway.conf -o ext_gateway.mod
 +
semodule_package -o ext_gateway.pp -m ext_gateway.mod -f gateway.fc
 +
checkmodule -m int_gateway.conf -o int_gateway.mod
 +
semodule_package -o int_gateway.pp -m int_gateway.mod
 +
semodule -s modular-test --priority 100 -i base.pp ext_gateway.pp int_gateway.pp
  
When these configuration files are used to configure a security context when the policy supports MCS / MLS, then the appropriate level or range should be added (generally an object like a file has a level, and a user or process (a subject) has a level and range, although directories can have a range if they support polyinstantiation).
+
# Compile and install an updated module written in CIL:>
 +
semodule -s modular-test --priority 400 -i custom/int_gateway.cil
 +
 
 +
# Show a full listing of modules:
 +
semodule -s modular-test --list-modules=full
 +
400 int_gateway cil
 +
100 base pp
 +
100 ext_gateway pp
 +
100 int_gateway pp
 +
 
 +
# Show a standard listing of modules:
 +
semodule -s modular-test --list-modules=standard
 +
base
 +
ext_gateway
 +
int_gateway
 +
</pre>
 +
 
 +
Note the use of <tt>--priority 100</tt> and <tt>--priority 400</tt> option that is available after migration for <tt>'''semodule'''(8)</tt>. This command has a number of new options, with the most significant being:
 +
# Setting module priorities (<tt>-X | --priority</tt>), this is discussed in [[#The priority Option | The priority Option]] section.
 +
# Listing modules (<tt>--list-modules=full | standard</tt>). The 'f<tt>ull</tt>' option shows all the available modules with their priority and policy format. The '<tt>standard</tt>' option will only show the highest priority, enabled modules.
 +
 
 +
==== The priority Option ====
 +
<ref name="ftn32">This text has been derived from: [http://marc.info/?l=selinux&m=141044198403718&w=2 http://marc.info/?l=selinux&m=141044198403718&w=2].</ref>Priorities allow multiple modules with the same name to exist in the policy store, with the higher priority module included in the final kernel binary, and all lower priority modules of the same name ignored. For example:
 +
<pre>
 +
semodule --priority 100 --install distribution/apache.pp
 +
semodule --priority 400 --install custom/apache.pp
 +
</pre>
 +
 
 +
Both apache modules are installed in the policy store as 'apache', but only the custom apache module is included in the final kernel binary. The distribution apache module is ignored. The <tt>--list-modules</tt> options can be used to show these:
 +
<pre>
 +
# Show a full listing of modules:
 +
semodule --list-modules=full
 +
400 apache pp
 +
100 base pp
 +
100 apache pp
 +
 
 +
# Show a standard listing of modules:
 +
semodule --list-modules=standard
 +
base
 +
apache
 +
</pre>
 +
 
 +
The main use case for this is the ability to override a distribution provided policy, while keeping the distribution policy in the store.
 +
 
 +
This makes it easy for distributions, 3rd parties, configuration management tools (e.g. puppet), local administrators, etc. to update policies without erasing each others changes. This also means that if a distribution, 3rd party etc. updates a module, providing the local customisation is installed at a higher priority, it will override the new distribution policy.
 +
 
 +
This does require that policy managers adopt some kind of scheme for who uses what priority. No strict guidelines currently exist, however the value used by the <tt>semanage_migrate_store</tt> script is <tt>--priority 100</tt> as this is assumed to be migrating a distribution. If a value is not provided, <tt>semodule</tt> will use a default of <tt>--priority 400</tt> as it is assumed to be a locally customised policy.
 +
 
 +
When <tt>semodule</tt> builds a lower priority module when a higher priority is already available, the following message will be given: "<tt><nowiki>A higher priority <name> module exists at priority <999> and will override the module currently being installed at priority <111></nowiki></tt>".
 +
 
 +
==== Converting policy packages to CIL ====
 +
A component of the update is to add a facility that converts compiled policy modules (known as policy packages or the <tt><nowiki>*.pp</nowiki></tt> files) to CIL format. This is achieved via a <tt>pp</tt> to CIL high level language conversion utility located at <tt>/usr/libexec/selinux/hll/pp</tt>. This utility can be used manually as follows:
 +
<pre>
 +
cat module_name.pp | /usr/libexec/selinux/hll/pp > module_name.cil
 +
</pre>
 +
 
 +
There is no man page for '<tt>pp</tt>', however the help text is as follows:
 +
<pre>
 +
Usage: pp [OPTIONS] [IN_FILE [OUT_FILE]]
 +
 
 +
Read an SELinux policy package (.pp) and output the equivilent CIL.
 +
If IN_FILE is not provided or is -, read SELinux policy package from
 +
standard input. If OUT_FILE is not provided or is -, output CIL to
 +
standard output.
 +
 
 +
Options:
 +
-h, --help print this message and exit
 +
</pre>
  
 
== Global Configuration Files ==
 
== Global Configuration Files ==
 
* The following files are described in the [[GlobalConfigurationFiles|Global Configuration Files]] section:
 
* The following files are described in the [[GlobalConfigurationFiles|Global Configuration Files]] section:
** /etc/selinux/config File
+
** /etc/selinux/config
** /etc/selinux/semanage.conf File
+
** /etc/selinux/semanage.conf
** /etc/selinux/restorecond.conf File
+
** /etc/selinux/restorecond.conf and restorecond-user.conf
** /etc/sestatus.conf File
+
** /etc/selinux/newrole_pam.conf
** /etc/security/sepermit.conf File
+
** /etc/sestatus.conf
 +
** /etc/security/sepermit.conf
  
 
== Policy Store Configuration Files ==
 
== Policy Store Configuration Files ==
 
* The following files are described in the [[PolicyStoreConfigurationFiles|Policy Store Configuration Files]] section:
 
* The following files are described in the [[PolicyStoreConfigurationFiles|Policy Store Configuration Files]] section:
** base.pp File
+
** modules/active/base.pp
** base.linked File
+
** modules/active/base.linked
** commit_num File
+
** modules/active/commit_num
** file_contexts.template File
+
** modules/active/file_contexts.template
** file_contexts File
+
** modules/active/file_contexts
** homedir_template File
+
** modules/active/homedir_template
** file_contexts.homedirs File
+
** modules/active/file_contexts.homedirs
** netfilter_contexts & netfilter.local File
+
** modules/active/netfilter_contexts & netfilter.local
** policy.kern File
+
** modules/active/policy.kern
** seusers.final and seusers Files
+
** modules/active/seusers.final and seusers
** users_extra, users_extra.local and users.local Files
+
** modules/active/users_extra, users_extra.local and users.local
** booleans.local File
+
** modules/active/booleans.local
** file_contexts.local File
+
** modules/active/file_contexts.local
** interfaces.local File
+
** modules/active/interfaces.local
** nodes.local File
+
** modules/active/nodes.local File
** ports.local File
+
** modules/active/ports.local File
** modules Directory Contents
+
** modules/active/preserve_tunables
 +
** modules/active/disable_dontaudit
 +
** modules/active/modules Directory Contents
  
 
== Policy Configuration Files ==
 
== Policy Configuration Files ==
 
* The following files are described in the [[PolicyConfigurationFiles|Policy Configuration Files]] section:
 
* The following files are described in the [[PolicyConfigurationFiles|Policy Configuration Files]] section:
** seusers File
+
** seusers
** setrans.conf File
+
** booleans and booleans.local
** secolor.conf File
+
** booleans.subs_dist
** <nowiki>policy/policy[ver] File</nowiki>
+
** setrans.conf
** contexts/customizable_types File
+
** secolor.conf
** contexts/default_contexts File
+
** <nowiki>policy/policy[ver]</nowiki>
** contexts/debus_contexts File
+
** contexts/customizable_types
** contexts/default_type File
+
** contexts/default_contexts
** contexts/failsafe_context File
+
** contexts/dbus_contexts
 +
** contexts/default_type
 +
** contexts/failsafe_context
 
** contexts/initrc_context File
 
** contexts/initrc_context File
** contexts/netfilter_contexts File
+
** contexts/lxc_contexts File
** contexts/removable_contexts File
+
** contexts/netfilter_contexts
** contexts/securetty_types File
+
** contexts/removable_context
** contexts/userhelper_context File
+
** contexts/securetty_types
** contexts/virtual_domain_context File
+
** contexts/sepgsql_contexts
** contexts/virtual_image_context File
+
** contexts/systemd_contexts
** contexts/x_contexts File
+
** contexts/userhelper_context
** contexts/files/file_contexts File
+
** contexts/virtual_domain_context
** contexts/files/file_contexts.local File
+
** contexts/virtual_image_context
** contexts/files/file_contexts.homedirs File
+
** contexts/x_contexts
** contexts/files/media File
+
** contexts/files/file_contexts
** <nowiki>contexts/users/[seuser_id] File</nowiki>
+
** contexts/files/file_contexts.local
 +
** contexts/files/file_contexts.homedirs
 +
** contexts/files/file_contexts.subs and file_contexts.subs_dist
 +
** contexts/files/media
 +
** <nowiki>contexts/users/[seuser_id]</nowiki>
 +
** <nowiki>logins/<linuxuser_id></nowiki>
 +
** users/local.users
  
 +
 +
{| style="width: 100%;" border="0"
 +
|-
 +
| [[NB_Apache | '''Previous''']]
 +
| <center>[[NewUsers | '''Home''']]</center>
 +
| <center>[[GlobalConfigurationFiles | '''Next''']]</center>
 +
|}
 +
 +
 +
----
 
<references/>
 
<references/>
 +
 +
[[Category:Notebook]]

Latest revision as of 15:06, 8 December 2014

SELinux Configuration Files

Introduction

This section explains each SELinux configuration file with its format, example content and where applicable, any supporting SELinux commands or libselinux library API function names.

Where configuration files have specific man pages, these are noted by adding the man page section (e.g. semanage.config(5)).

This Notebook classifies the types of configuration file used in SELinux as follows:

The Policy Store Configuration files are 'private'[1] and managed by the semanage(8) and semodule(8) commands[2]. These are used to build the majority of the Policy Configuration Files. This store will be moving as part of a migration programme, see https://github.com/SELinuxProject/selinux/wiki/Policy-Store-Migration and Policy Store Migration for details.
Note there can be multiple policy configuration areas on a system (e.g. /etc/selinux/targeted and /etc/selinux/mls), however only one can be the active policy).
  • SELinux Kernel Configuration files located under the /sys/fs/selinux directory and reflect the current configuration of SELinux for the active policy. This area is used extensively by the libselinux library for userspace object managers and other SELinux-aware applications. These files and directories should not be updated by users (the majority are read only anyway), however they can be read to check various configuration parameters.

Policy Store Migration

When distributions move to version 2.4 of libsemanage, libsepol, and policycoreutils the policy module store will move from /etc/selinux/<SELINUXTYPE>/modules to /var/lib/selinux/<SELINUXTYPE>. Once the libraries are upgraded, all policy stores must be migrated before any commands can be executed that modify or use the store, for example semodule(8) or semanage(8). See https://github.com/SELinuxProject/selinux/wiki/Policy-Store-Migration for details.

Once the migration is complete:

  • The policy store configuration files will no longer be available.
  • It will be possible to build policies containing a mixture of Reference Policy modules, kernel policy language modules and modules written in the CIL language as shown in the following example:
# Compile and install a base and two modules written in kernel language:
checkmodule -o base.mod base.conf
semodule_package -o base.pp -m base.mod -f base.fc
checkmodule -m ext_gateway.conf -o ext_gateway.mod
semodule_package -o ext_gateway.pp -m ext_gateway.mod -f gateway.fc
checkmodule -m int_gateway.conf -o int_gateway.mod
semodule_package -o int_gateway.pp -m int_gateway.mod
semodule -s modular-test --priority 100 -i base.pp ext_gateway.pp int_gateway.pp

# Compile and install an updated module written in CIL:>
semodule -s modular-test --priority 400 -i custom/int_gateway.cil

# Show a full listing of modules:
semodule -s modular-test --list-modules=full
400 int_gateway cil
100 base pp
100 ext_gateway pp
100 int_gateway pp

# Show a standard listing of modules:
semodule -s modular-test --list-modules=standard
base
ext_gateway
int_gateway

Note the use of --priority 100 and --priority 400 option that is available after migration for semodule(8). This command has a number of new options, with the most significant being:

  1. Setting module priorities (-X | --priority), this is discussed in The priority Option section.
  2. Listing modules (--list-modules=full | standard). The 'full' option shows all the available modules with their priority and policy format. The 'standard' option will only show the highest priority, enabled modules.

The priority Option

[3]Priorities allow multiple modules with the same name to exist in the policy store, with the higher priority module included in the final kernel binary, and all lower priority modules of the same name ignored. For example:

semodule --priority 100 --install distribution/apache.pp
semodule --priority 400 --install custom/apache.pp

Both apache modules are installed in the policy store as 'apache', but only the custom apache module is included in the final kernel binary. The distribution apache module is ignored. The --list-modules options can be used to show these:

# Show a full listing of modules:
semodule --list-modules=full
400 apache pp
100 base pp
100 apache pp

# Show a standard listing of modules:
semodule --list-modules=standard
base
apache

The main use case for this is the ability to override a distribution provided policy, while keeping the distribution policy in the store.

This makes it easy for distributions, 3rd parties, configuration management tools (e.g. puppet), local administrators, etc. to update policies without erasing each others changes. This also means that if a distribution, 3rd party etc. updates a module, providing the local customisation is installed at a higher priority, it will override the new distribution policy.

This does require that policy managers adopt some kind of scheme for who uses what priority. No strict guidelines currently exist, however the value used by the semanage_migrate_store script is --priority 100 as this is assumed to be migrating a distribution. If a value is not provided, semodule will use a default of --priority 400 as it is assumed to be a locally customised policy.

When semodule builds a lower priority module when a higher priority is already available, the following message will be given: "A higher priority <name> module exists at priority <999> and will override the module currently being installed at priority <111>".

Converting policy packages to CIL

A component of the update is to add a facility that converts compiled policy modules (known as policy packages or the *.pp files) to CIL format. This is achieved via a pp to CIL high level language conversion utility located at /usr/libexec/selinux/hll/pp. This utility can be used manually as follows:

cat module_name.pp | /usr/libexec/selinux/hll/pp > module_name.cil

There is no man page for 'pp', however the help text is as follows:

Usage: pp [OPTIONS] [IN_FILE [OUT_FILE]]

Read an SELinux policy package (.pp) and output the equivilent CIL.
If IN_FILE is not provided or is -, read SELinux policy package from
standard input. If OUT_FILE is not provided or is -, output CIL to
standard output.

Options:
-h, --help print this message and exit

Global Configuration Files

  • The following files are described in the Global Configuration Files section:
    • /etc/selinux/config
    • /etc/selinux/semanage.conf
    • /etc/selinux/restorecond.conf and restorecond-user.conf
    • /etc/selinux/newrole_pam.conf
    • /etc/sestatus.conf
    • /etc/security/sepermit.conf

Policy Store Configuration Files

  • The following files are described in the Policy Store Configuration Files section:
    • modules/active/base.pp
    • modules/active/base.linked
    • modules/active/commit_num
    • modules/active/file_contexts.template
    • modules/active/file_contexts
    • modules/active/homedir_template
    • modules/active/file_contexts.homedirs
    • modules/active/netfilter_contexts & netfilter.local
    • modules/active/policy.kern
    • modules/active/seusers.final and seusers
    • modules/active/users_extra, users_extra.local and users.local
    • modules/active/booleans.local
    • modules/active/file_contexts.local
    • modules/active/interfaces.local
    • modules/active/nodes.local File
    • modules/active/ports.local File
    • modules/active/preserve_tunables
    • modules/active/disable_dontaudit
    • modules/active/modules Directory Contents

Policy Configuration Files

  • The following files are described in the Policy Configuration Files section:
    • seusers
    • booleans and booleans.local
    • booleans.subs_dist
    • setrans.conf
    • secolor.conf
    • policy/policy[ver]
    • contexts/customizable_types
    • contexts/default_contexts
    • contexts/dbus_contexts
    • contexts/default_type
    • contexts/failsafe_context
    • contexts/initrc_context File
    • contexts/lxc_contexts File
    • contexts/netfilter_contexts
    • contexts/removable_context
    • contexts/securetty_types
    • contexts/sepgsql_contexts
    • contexts/systemd_contexts
    • contexts/userhelper_context
    • contexts/virtual_domain_context
    • contexts/virtual_image_context
    • contexts/x_contexts
    • contexts/files/file_contexts
    • contexts/files/file_contexts.local
    • contexts/files/file_contexts.homedirs
    • contexts/files/file_contexts.subs and file_contexts.subs_dist
    • contexts/files/media
    • contexts/users/[seuser_id]
    • logins/<linuxuser_id>
    • users/local.users


Previous
Home
Next



  1. They should NOT be edited as together they describe the 'policy'.
  2. The system-config-selinux GUI (supplied in the polycoreutils-gui rpm) can also be used to manage users, booleans and the general configuration of SELinux as it calls semanage(8), however it does not manage all that the semanage command can (it also gets bitter & twisted if there are no MCS/MLS labels on some operations).
  3. This text has been derived from: http://marc.info/?l=selinux&m=141044198403718&w=2.