Add TOC and tidy up formatting. Signed-off-by: Richard Haines <richard_c_haines@xxxxxxxxxxxxxx> --- src/policy_store_config_files.md | 432 +++++++++++++++++-------------- 1 file changed, 234 insertions(+), 198 deletions(-) diff --git a/src/policy_store_config_files.md b/src/policy_store_config_files.md index 3e7f8ab..93d3727 100644 --- a/src/policy_store_config_files.md +++ b/src/policy_store_config_files.md @@ -1,23 +1,47 @@ # Policy Store Configuration Files -**NOTE: Files in this area are private and subject to change, they should only -be modified using the** ***semodule**(8)* and ***semanage**(8)* commands. +- [*active/modules* Directory Contents](#activemodules-directory-contents) + - [*tmp* Policy Store (build failure)](#tmp-policy-store-build-failure) +- [*active/commit_num*](#activecommit_num) + - [*active/policy.kern*](#activepolicy.kern) +- [*active/policy.linked*](#activepolicy.linked) +- [*active/seusers.linked*](#activeseusers.linked) +- [*active/seusers_extra.linked*](#activeseusers_extra.linked) +- [*active/booleans.local*](#activebooleans.local) +- [*disable_dontaudit*](#disable_dontaudit) +- [*active/file_contexts*](#activefile_contexts) + - [Building the File Labeling Support Files](#building-the-file-labeling-support-files) +- [*active/file_contexts.local*](#activefile_contexts.local) +- [*active/homedir_template*](#activehomedir_template) + - [*active/file_contexts.homedirs*](#activefile_contexts.homedirs) +- [*active/seusers*](#activeseusers) +- [*active/seusers.local*](#activeseusers.local) +- [*active/users_extra*](#activeusers_extra) +- [*active/users_extra.local*](#activeusers_extra.local) +- [*active/users.local*](#activeusers.local) +- [*active/interfaces.local*](#activeinterfaces.local) +- [*active/nodes.local*](#activenodes.local) +- [*active/ports.local*](#activeports.local) +- [Set domain permissive mode](#set-domain-permissive-mode) + +**NOTE:** Files in this area are private and subject to change, they should only +be modified using the ***semodule**(8)* and ***semanage**(8)* commands. Depending on the SELinux userspace library release being used the default policy stores will be located at: -- */etc/selinux/<SELINUXTYPE>/modules* - This is the default for - systems that support versions < 2.4 of the SELinux userspace library. - The migration process to >= 2.4 is described at - <https://github.com/SELinuxProject/selinux/wiki/Policy-Store-Migration>. -- */var/lib/selinux* - This is the default base for systems that - support versions >= 2.4 of the SELinux userspace library. This base - may be overridden by the ***store-root*** parameter defined in the - [***semanage.conf**(5)*](global_config_files.md#etcselinuxsemanage.conf) - file. Multiple policy stores are supported by appending the - *<SELINUXTYPE>*, for example: -- */var/lib/selinux/mls* -- */var/lib/selinux/targeted* +- */etc/selinux/\<SELINUXTYPE\>/modules* - This is the default for + systems that support versions \< 2.4 of the SELinux userspace library. + The migration process to \>= 2.4 is described at + <https://github.com/SELinuxProject/selinux/wiki/Policy-Store-Migration>. +- */var/lib/selinux* - This is the default base for systems that + support versions \>= 2.4 of the SELinux userspace library. This base + may be overridden by the ***store-root*** parameter defined in the + [***semanage.conf**(5)*](global_config_files.md#etcselinuxsemanage.conf) + file. Multiple policy stores are supported by appending the + *\<SELINUXTYPE\>*, for example: + - */var/lib/selinux/mls* + - */var/lib/selinux/targeted* The Policy Store files are either installed, updated or built by the ***semodule**(8)* and ***semanage**(8)* commands as a part of the build @@ -25,34 +49,35 @@ process with the resulting files being copied over to the [**The Policy Store**](configuration_files.md#the-policy-store) area. The policy configuration files are described relative to the default -***store-root*** at */var/lib/selinux* with *<SELINUXTYPE>* being +***store-root*** at */var/lib/selinux* with *\<SELINUXTYPE\>* being *targeted*. The ***semanage**(8)* command must be used to configure policy (the actual policy and supporting configuration files) within a specific **Policy Store**. The command types are: -- [***semanage boolean***](#activebooleans.local) Manage booleans to - selectively enable functionality -- [***semanage dontaudit***](#disable_dontaudit) Disable/Enable *dontaudit* - rules in policy -- ***semanage export*** Output local customizations -- [***semanage fcontext***](#activefile_contexts.local) Manage file context - mapping definitions -- ***semanage ibendport*** Manage infiniband end port type definitions -- ***semanage ibpkey*** Manage infiniband pkey type definitions -- ***semanage import*** Import local customizations -- [***semanage interface***](#activeinterfaces.local) Manage network interface - type definitions -- [***semanage login***](#activeseusers.local) Manage login mappings between - linux users and SELinux confined users -- [***semanage module***](#activemodules-directory-contents) Manage SELinux - policy modules -- [***semanage node***](#activenodes.local) Manage network node type definitions -- [***semanage permissive***](#set-domain-permissive-mode) Manage process - type enforcement mode. -- [***semanage port***](#activeports.local) Manage network port type definitions -- [***semanage user***](#activeusers.local) Manage SELinux confined users -(Roles and levels for an SELinux user) + +- [***semanage boolean***](#activebooleans.local) Manage booleans to + selectively enable functionality +- [***semanage dontaudit***](#disable_dontaudit) Disable/Enable *dontaudit* + rules in policy +- ***semanage export*** Output local customizations +- [***semanage fcontext***](#activefile_contexts.local) Manage file context + mapping definitions +- ***semanage ibendport*** Manage infiniband end port type definitions +- ***semanage ibpkey*** Manage infiniband pkey type definitions +- ***semanage import*** Import local customizations +- [***semanage interface***](#activeinterfaces.local) Manage network interface + type definitions +- [***semanage login***](#activeseusers.local) Manage login mappings between + linux users and SELinux confined users +- [***semanage module***](#activemodules-directory-contents) Manage SELinux + policy modules +- [***semanage node***](#activenodes.local) Manage network node type definitions +- [***semanage permissive***](#set-domain-permissive-mode) Manage process + type enforcement mode. +- [***semanage port***](#activeports.local) Manage network port type definitions +- [***semanage user***](#activeusers.local) Manage SELinux confined users + (Roles and levels for an SELinux user) ## active/modules Directory Contents @@ -84,8 +109,8 @@ test_policy 400 pp ### *tmp* Policy Store (build failure) -When adding/updating a policy module and it fails to build for some reason, -the *tmp* directory (*/var/lib/selinux<SELINUXTYPE>/tmp*) will contain +When adding/updating a policy module and it fails to build for some reason, +the *tmp* directory (*/var/lib/selinux\<SELINUXTYPE\>/tmp*) will contain a copy of the failed policy for inspection. An example ***semodule*** failure message indicating the failing line number is: @@ -103,7 +128,7 @@ store. The format is not relevant to policy construction. This is the binary policy file built by either the ***semanage**(8)* or ***semodule**(8)* commands (depending on the configuration action), that is then becomes the -*/etc/selinux/<SELINUXTYPE>/policy/policy.<ver>* binary policy +*/etc/selinux/\<SELINUXTYPE\>/policy/policy.\<ver\>* binary policy that will be loaded into the kernel. ## *active/policy.linked* @@ -145,7 +170,7 @@ such as ***audit2allow**(8)* to list all denials to assist debugging policy. ## *active/file_contexts* This file becomes the policy -[*/etc/selinux/<SELINUXTYPE>/contexts/files/file_contexts*](policy_config_files.md#contextsfilesfile_contexts) +[*/etc/selinux/\<SELINUXTYPE\>/contexts/files/file_contexts*](policy_config_files.md#contextsfilesfile_contexts) file. It is built as described in the [**Building the File Labeling Support Files**](#building-the-file-labeling-support-files) section. @@ -210,18 +235,18 @@ section. The process used to build the *file_contexts* and the *file_contexts.template* files is shown in **Figure 25: File Context Configuration Files**. -1. They are built by ***semanage**(8)* using entries from the 'Policy File - Labeling' statements extracted from the - [*active/modules*](#activemodules-directory-contents) entries - (the *<module_name>.fc* files, this will include any CIL *(filecon ....)* - statements that are within CIL policy files). -2. As a part of the ***semanage**(8)* build process, these two files - will also have *file_contexts.bin* and *file_contexts.homedirs.bin* - files present in the - [Policy Configuration Files](policy_config_files.md#contextsfilesfile_contexts) - *./contexts/files* directory. This is because ***semanage**(8)* requires - these in the Perl compatible regular expression (PCRE) internal format. - They are generated by the ***sefcontext_compile**(8)* utility. +1. They are built by ***semanage**(8)* using entries from the 'Policy File + Labeling' statements extracted from the + [*active/modules*](#activemodules-directory-contents) entries + (the *\<module_name\>.fc* files, this will include any CIL *(filecon ....)* + statements that are within CIL policy files). +2. As a part of the ***semanage**(8)* build process, these two files + will also have *file_contexts.bin* and *file_contexts.homedirs.bin* + files present in the + [Policy Configuration Files](policy_config_files.md#contextsfilesfile_contexts) + *./contexts/files* directory. This is because ***semanage**(8)* requires + these in the Perl compatible regular expression (PCRE) internal format. + They are generated by the ***sefcontext_compile**(8)* utility.  @@ -237,66 +262,82 @@ pathname_regexp [file_type] security_context | <<none>> **Where:** -<table> -<tbody> -<tr> -<td><code>pathname_regexp</code></td> -<td><p>An entry that defines the pathname that may be in the form of a regular expression.</p> -<p>The metacharacters '^' (match beginning of line) and '$' (match end of line) are automatically added to the expression by the routines that process this file, however they can be over-ridden by using '.*' at either the beginning or end of the expression (see the example <em>file_contexts</em> files below). </p> -<p>The source policy <em>*.fc</em> and f<em>ile_contexts.template</em> files may also contain the keywords HOME_ROOT, HOME_DIR, ROLE and USER that will be replaced as explained in the next table.</p></td> -</tr> -<tr> -<td><code>file_type</code></td> -<td><p>One of the following optional file_type entries (note if blank means "all file types"):</p> -<p>'<em>-b</em>' - Block Device '<em>-c</em>' - Character Device</p> -<p>'<em>-d</em>' - Directory '<em>-p</em>' - Named Pipe (FIFO)</p> -<p>'<em>-l</em>' - Symbolic Link '<em>-s</em>' - Socket File</p> -<p>'<em>--</em>' - Ordinary file</p> -<p>By convention this entry is known as 'file type', however it really represents the 'file object class'.</p></td> -</tr> -<tr> -<td><code>security_context</code></td> -<td>This entry can be either: -<p>a. The security context, including the MLS / MCS level or range if applicable that will be assigned to the file.</p> -<p>b. A value of <<none>> can be used to indicate that matching files should not be re-labeled.</p></td> -</tr> -</tbody> -</table> - -Keywords that can be in policy source \*.fc files and then form the *file_contexts.template* file entries are: - -<table> -<tbody> -<tr> -<td>HOME_ROOT</td> -<td>This keyword is replaced by the Linux users root home directory, normally <em>/home</em> is the default.</td> -</tr> -<tr> -<td>HOME_DIR</td> -<td>This keyword is replaced by the Linux users home directory, normally <em>/home/</em> is the default.</td> -</tr> -<tr> -<td>USER</td> -<td>This keyword will be replaced by the users Linux user id.</td> -</tr> -<tr> -<td>ROLE</td> -<td><p>This keyword is replaced by the <code>prefix</code> entry from the users_extra configuration file that corresponds to the SELinux users user id. Example users_extra configuration file entries are:</p> -<p><code>user user_u prefix user;</code></p> -<p><code>user staff_u prefix staff;</code></p> -<p>It is used for files and directories within the users home directory area. </p> -<p>The prefix can be added by the semanage <em>login</em> command as follows (although note that the <em>-P</em> option is suppressed when help is displayed as it is generally it is not used (defaults to <em>user</em>:</p> -<p># Add a Linux user:</p> -<p><code>adduser rch</code></p> -<p># Modify staff_u SELinux user and prefix:</p> -<p><code>semanage user -m -R staff_r -P staff staff_u</code></p> -<p># Associate the SELinux user to the Linux user:</p> -<p><code>semanage login -a -s staff_u rch</code></p></td> -</tr> -</tbody> -</table> - -**Example policy source file from Reference Policy** *policy/modules/system/userdomain.fc*: +*pathname_regexp* + +- An entry that defines the pathname that may be in the form of a regular + expression. The metacharacters '^' (match beginning of line) and '\$' + (match end of line) are automatically added to the expression by the + routines that process this file, however they can be over-ridden by + using '\.\*' at either the beginning or end of the expression (see the + example *file_contexts* files below). +- The source policy *\*.fc* and *file_contexts.template* files may also + contain the keywords *HOME_ROOT*, *HOME_DIR*, *ROLE* and *USER* that will + be replaced as explained in the next table. + +*file_type* + +- One of the following optional file_type entries (note if blank means + "all file types"): + - *-b* - Block Device + - *-c* - Character Device + - *-d* - Directory + - *-p* - Named Pipe (FIFO) + - *-l* - Symbolic Link + - *-s* - Socket File + - *\-\-* - Ordinary file +- By convention this entry is known as *file type*, however it really + represents the 'file object class'. + +*security_context* + +- This entry can be either: + - The security context, including the MLS / MCS level or range if applicable + that will be assigned to the file. + - A value of \<\<none\>\> can be used to indicate that matching files should + not be re-labeled. + +Keywords that can be in policy source \*.fc files and then form the +*file_contexts.template* file entries are: + +*HOME_ROOT* + +- This keyword is replaced by the Linux users root home directory, + normally */home* is the default. + +*HOME_DIR* + +- This keyword is replaced by the Linux users home directory, + normally */home/* is the default. + +*USER* + +- This keyword will be replaced by the users Linux user id. + +*ROLE* + +- This keyword is replaced by the *prefix* entry from the *users_extra* + configuration file that corresponds to the SELinux users user id. Example + *users_extra* configuration file entries are: + - *user user_u prefix user;* + - *user staff_u prefix staff;* +- It is used for files and directories within the users home directory area. + The prefix can be added by the semanage *login* command as follows + (although note that the *-P* option is suppressed when help is displayed + as it is generally it is not used (defaults to *user*)): + +``` +# Add a Linux user: + +adduser rch +# Modify staff_u SELinux user and prefix: +semanage user -m -R staff_r -P staff staff_u + +# Associate the SELinux user to the Linux user: +semanage login -a -s staff_u rch +``` + +**Example policy source file from Reference Policy** +*policy/modules/system/userdomain.fc*: ``` HOME_DIR -d gen_context(system_u:object_r:user_home_dir_t,s0-mls_systemhigh) @@ -309,7 +350,8 @@ HOME_DIR/.+ gen_context(system_u:object_r:user_home_t,s0) /root/\.debug(/.*)? <<none>> ``` -**Example policy source file from Reference Policy** *policy/modules/kernel/files.fc*: +**Example policy source file from Reference Policy** +*policy/modules/kernel/files.fc*: ``` # @@ -387,8 +429,8 @@ HOME_DIR/.+ system_u:object_r:user_home_t:s0 ### *active/file_contexts.homedirs* This file becomes the policy -[*/etc/selinux/<SELINUXTYPE>/contexts/files/file_contexts.homedirs*](policy_config_files.md#contextsfilesfile_contexts.homedirs) file. It is built -as described in the +[*/etc/selinux/\<SELINUXTYPE\>/contexts/files/file_contexts.homedirs*](policy_config_files.md#contextsfilesfile_contexts.homedirs) +file. It is built as described in the [**Building the File Labeling Support Files**](#building-the-file-labeling-support-files) section. It is then used by the file labeling utilities to ensure that users home directory areas are labeled according to the policy. @@ -419,32 +461,32 @@ libsepol library function. /home/[^/]+/.+ unconfined_u:object_r:user_home_t:s0 ``` -## active/seusers -## active/seusers.local +## *active/seusers* +## *active/seusers.local* -The *active/seusers* file becomes the policy */etc/selinux/<SELINUXTYPE>/seusers* +The *active/seusers* file becomes the policy */etc/selinux/\<SELINUXTYPE\>/seusers* file, the *active/seusers.local* file holds entries added when adding users via ***semanage**(8)*. The *seusers* file is built or modified when: -1. Building a policy where an optional *seusers* file has been included - in the base package via the ***semodule_package**(8)* command - (signified by the *-s* flag) as follows: -- *semodule_package -o base.pp -m base.mod -s seusers ...* -- The *seusers* file would be extracted by the subsequent ***semodule*** command - when building the policy to produce the *seusers.final* file. -2. The ***semanage login*** command is used to map Linux users to - SELinux users as follows: -- *semanage login -a -s staff_u rch* -- This action will update the *seusers* file that would then be used to - produce the seusers.final file with both policy and locally defined user - mapping. -3. It is also possible to associate a Linux group of users to an - SELinux user as follows: -- *semanage login -a -s staff_u %staff_group* - -**The format of the** *seusers* & *seusers.local* **files are as follows:** +1. Building a policy where an optional *seusers* file has been included + in the base package via the ***semodule_package**(8)* command + (signified by the *-s* flag) as follows: + - *semodule_package -o base.pp -m base.mod -s seusers ...* + - The *seusers* file would be extracted by the subsequent ***semodule*** + command when building the policy to produce the *seusers.final* file. +2. The ***semanage login*** command is used to map Linux users to + SELinux users as follows: + - *semanage login -a -s staff_u rch* + - This action will update the *seusers* file that would then be used to + produce the seusers.final file with both policy and locally defined user + mapping. +3. It is also possible to associate a Linux group of users to an + SELinux user as follows: + - *semanage login -a -s staff_u %staff_group* + +**The format of the** *seusers* and *seusers.local* **files are as follows:** ``` [%]user_id:seuser_id[:range] @@ -452,22 +494,18 @@ The *seusers* file is built or modified when: **Where:** -<table> -<tbody> -<tr> -<td>user_id</td> -<td>Where <em>user_id</em> is the Linux user identity. If this is a Linux <em>group_id</em> then it will be preceded with the '<em>%</em>' sign as shown in the example below.</td> -</tr> -<tr> -<td>seuser_id</td> -<td>The SELinux user identity.</td> -</tr> -<tr> -<td>range</td> -<td>The optional <em>level</em> or range.</td> -</tr> -</tbody> -</table> +*user_id* + +- Where *user_id* is the Linux user identity. If this is a Linux *group_id* + then it will be preceded with the '*%*' sign as shown in the example below. + +*seuser_id* + +- The SELinux user identity. + +*range* + +- The optional *level* or *range*. **Example** *seusers* **file contents:** @@ -510,32 +548,32 @@ rch:user_u:s0 These three files work together to describe SELinux user information as follows: -1. The *users_extra* and *users_extra.local* files are used to map a - *prefix* to a users home directories as discussed in the - [**Building the File Labeling Support Files**](#building-the-file-labeling-support-files) - section, where it is used to replace the *ROLE* keyword. The - *prefix* is linked to an SELinux user id and should reflect the users role. -- The *users_extra* file contains all the policy *prefix* entries, and the - *users_extra.local* file contains those generated by the ***semanage user*** - command. -- The *users_extra* file can optionally be included in the base package via - the ***semodule_package**(8)* command (signified by the *-u* flag) as - follows: -- *semodule_package -o base.pp -m base.mod -u users_extra ...* -- The *users_extra* file would then be extracted by a subsequent semodule - command when building the policy. -2. The *users.local* file is used to add new SELinux users to the policy - without editing the policy source itself (with each line in the file - following a policy language - [**user Statement**](user_statements.md#user-statements)). - This is useful when only the Reference Policy headers are installed and - additional users need to be added. The ***semanage user*** command will allow - a new SELinux user to be added that would generate the *user.local* file - and if a *-P* flag has been specified, then a *users_extra.local* file is also - updated (note: if this is a new SELinux user and a prefix is not specified - a default *prefix* of user is generated). - -**The format of the** *users_extra* & *users_extra.local* **files are:** +1. The *users_extra* and *users_extra.local* files are used to map a + *prefix* to a users home directories as discussed in the + [**Building the File Labeling Support Files**](#building-the-file-labeling-support-files) + section, where it is used to replace the *ROLE* keyword. The + *prefix* is linked to an SELinux user id and should reflect the users role. + - The *users_extra* file contains all the policy *prefix* entries, and the + *users_extra.local* file contains those generated by the + ***semanage user*** command. + - The *users_extra* file can optionally be included in the base package via + the ***semodule_package**(8)* command (signified by the *-u* flag) as + follows: + - *semodule_package -o base.pp -m base.mod -u users_extra ...* + - The *users_extra* file would then be extracted by a subsequent semodule + command when building the policy. +2. The *users.local* file is used to add new SELinux users to the policy + without editing the policy source itself (with each line in the file + following a policy language + [**user Statement**](user_statements.md#user-statements)). + This is useful when only the Reference Policy headers are installed and + additional users need to be added. The ***semanage user*** command will allow + a new SELinux user to be added that would generate the *user.local* file + and if a *-P* flag has been specified, then a *users_extra.local* file is also + updated (note: if this is a new SELinux user and a prefix is not specified + a default *prefix* of user is generated). + +**The format of the** *users_extra* and *users_extra.local* **files are:** ``` user seuser_id prefix prefix_id; @@ -543,26 +581,24 @@ user seuser_id prefix prefix_id; **Where:** -<table> -<tbody> -<tr> -<td>user</td> -<td>The user keyword.</td> -</tr> -<tr> -<td>seuser_id</td> -<td>The SELinux user identity.</td> -</tr> -<tr> -<td>prefix</td> -<td>The prefix keyword.</td> -</tr> -<tr> -<td>prefix_id</td> -<td>An identifier that will be used to replace the ROLE keyword within the active/homedir_template file when building the active/file_contexts.homedirs file for the relabeling utilities to set the security context on users home directories.</td> -</tr> -</tbody> -</table> +*user* + +- The user keyword. + +*seuser_id* + +- The SELinux user identity. + +*prefix* + +- The prefix keyword. + +*prefix_id* + +- An identifier that will be used to replace the *ROLE* keyword within the + *active/homedir_template* file when building the + *active/file_contexts.homedirs* file for the relabeling utilities to set + the security context on users home directories. **Example** *users_extra* **file contents:** -- 2.26.2
