From 5629c0a6d5fa329688e60040e7aeb0bcd58eb4a5 Mon Sep 17 00:00:00 2001 From: Peter Boy Date: Aug 10 2023 04:58:01 +0000 Subject: Performed review, updated links, etc. --- diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 4ba86ff..692273c 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -84,9 +84,9 @@ *** xref:bumblebee.adoc[NVIDIA Optimus Bumblebee] *** xref:how-to-set-nvidia-as-primary-gpu-on-optimus-based-laptops.adoc[How to Set NVIDIA as Primary GPU on Optimus-based Laptops] -* xref:getting-started-with-selinux.adoc[SELinux] -** xref:changing-selinux-states-and-modes.adoc[Changing SELinux states and modes] -** xref:troubleshooting_selinux.adoc[Troubleshooting SELinux] +* xref:selinux-getting-started.adoc[SELinux] +** xref:selinux-changing-states-and-modes.adoc[Changing SELinux states and modes] +** xref:selinux-troubleshooting.adoc[Troubleshooting SELinux] * xref:upgrading.adoc[Upgrading to a new release] ** xref:dnf-system-upgrade.adoc[Upgrading Fedora using the DNF system upgrade] diff --git a/modules/ROOT/pages/_partials/2delete-con_benefits-of-selinux.adoc b/modules/ROOT/pages/_partials/2delete-con_benefits-of-selinux.adoc new file mode 100644 index 0000000..4f32531 --- /dev/null +++ b/modules/ROOT/pages/_partials/2delete-con_benefits-of-selinux.adoc @@ -0,0 +1,29 @@ +// Module included in the following assemblies: +// +// getting-started-with-selinux.adoc +:experimental: + +[#{context}-benefits-of-selinux] += Benefits of running SELinux + +SELinux provides the following benefits: + +* All processes and files are labeled. SELinux policy rules define how processes interact with files, as well as how processes interact with each other. Access is only allowed if an SELinux policy rule exists that specifically allows it. + +* Fine-grained access control. Stepping beyond traditional UNIX permissions that are controlled at user discretion and based on Linux user and group IDs, SELinux access decisions are based on all available information, such as an SELinux user, role, type, and, optionally, a security level. + +* SELinux policy is administratively-defined and enforced system-wide. + +* Improved mitigation for privilege escalation attacks. Processes run in domains, and are therefore separated from each other. SELinux policy rules define how processes access files and other processes. If a process is compromised, the attacker only has access to the normal functions of that process, and to files the process has been configured to have access to. For example, if the Apache HTTP Server is compromised, an attacker cannot use that process to read files in user home directories, unless a specific SELinux policy rule was added or configured to allow such access. + +* SELinux can be used to enforce data confidentiality and integrity, as well as protecting processes from untrusted inputs. + +However, SELinux is not: + +* antivirus software, + +* replacement for passwords, firewalls, and other security systems, + +* all-in-one security solution. + +SELinux is designed to enhance existing security solutions, not replace them. Even when running SELinux, it is important to continue to follow good security practices, such as keeping software up-to-date, using hard-to-guess passwords, or firewalls. diff --git a/modules/ROOT/pages/_partials/2delete-con_introduction-to-selinux.adoc b/modules/ROOT/pages/_partials/2delete-con_introduction-to-selinux.adoc new file mode 100644 index 0000000..29a262a --- /dev/null +++ b/modules/ROOT/pages/_partials/2delete-con_introduction-to-selinux.adoc @@ -0,0 +1,39 @@ +// Module included in the following assemblies: +// +// getting-started-with-selinux.adoc + +[#{context}-introduction-to-selinux] += Introduction to SELinux + +Security Enhanced Linux (SELinux) provides an additional layer of system security. SELinux fundamentally answers the question: _May do to ?_, for example: _May a web server access files in users' home directories?_ + +The standard access policy based on the user, group, and other permissions, known as Discretionary Access Control (DAC), does not enable system administrators to create comprehensive and fine-grained security policies, such as restricting specific applications to only viewing log files, while allowing other applications to append new data to the log files. + +SELinux implements Mandatory Access Control (MAC). Every process and system resource has a special security label called a _SELinux context_. A SELinux context, sometimes referred to as a _SELinux label_, is an identifier which abstracts away the system-level details and focuses on the security properties of the entity. Not only does this provide a consistent way of referencing objects in the SELinux policy, but it also removes any ambiguity that can be found in other identification methods; for example, a file can have multiple valid path names on a system that makes use of bind mounts. + +The SELinux policy uses these contexts in a series of rules which define how processes can interact with each other and the various system resources. By default, the policy does not allow any interaction unless a rule explicitly grants access. + +[NOTE] +==== +It is important to remember that SELinux policy rules are checked after DAC rules. SELinux policy rules are not used if DAC rules deny access first, which means that no SELinux denial is logged if the traditional DAC rules prevent the access. +==== + +SELinux contexts have several fields: user, role, type, and security level. The SELinux type information is perhaps the most important when it comes to the SELinux policy, as the most common policy rule which defines the allowed interactions between processes and system resources uses SELinux types and not the full SELinux context. SELinux types usually end with `_t`. For example, the type name for the web server is `httpd_t`. The type context for files and directories normally found in `/var/www/html/` is `httpd_sys_content_t`. The type contexts for files and directories normally found in `/tmp` and `/var/tmp/` is `tmp_t`. The type context for web server ports is `http_port_t`. + +For example, there is a policy rule that permits Apache (the web server process running as `httpd_t`) to access files and directories with a context normally found in `/var/www/html/` and other web server directories (`httpd_sys_content_t`). There is no allow rule in the policy for files normally found in `/tmp` and `/var/tmp/`, so access is not permitted. With SELinux, even if Apache is compromised, and a malicious script gains access, it is still not able to access the `/tmp` directory. + +[#fig-intro-httpd-mysqld] +.SELinux allows the Apache process running as httpd_t to access the /var/www/html/ directory and it denies the same process to access the /data/mysql/ directory because there is no allow rule for the httpd_t and mysqld_db_t type contexts). On the other hand, the MariaDB process running as mysqld_t is able to access the /data/mysql/ directory and SELinux also correctly denies the process with the mysqld_t type to access the /var/www/html/ directory labeled as httpd_sys_content_t. +image::selinux-intro-apache-mariadb.png[SELinux_Apache_MariaDB_example] + +[discrete] +== Additional resources +To better understand SELinux basic concepts, see the following documentation: + +* link:++https://people.redhat.com/duffy/selinux/selinux-coloring-book_A4-Stapled.pdf++[The SELinux Coloring Book] + +* link:++https://people.redhat.com/tcameron/Summit2012/SELinux/cameron_w_120_selinux_for_mere_mortals.pdf++[SELinux for Mere Mortals] + +* link:++http://selinuxproject.org/page/FAQ++[SELinux Wiki FAQ] + +* link:++http://freecomputerbooks.com/books/The_SELinux_Notebook-4th_Edition.pdf++[The SELinux Notebook] diff --git a/modules/ROOT/pages/_partials/2delete-con_selinux-architecture.adoc b/modules/ROOT/pages/_partials/2delete-con_selinux-architecture.adoc new file mode 100644 index 0000000..f636ef8 --- /dev/null +++ b/modules/ROOT/pages/_partials/2delete-con_selinux-architecture.adoc @@ -0,0 +1,11 @@ +// Module included in the following assemblies: +// +// getting-started-with-selinux.adoc +:experimental: + +[#{context}-selinux-architecture] += SELinux architecture + +SELinux is a Linux Security Module (LSM) that is built into the Linux kernel. The SELinux subsystem in the kernel is driven by a security policy which is controlled by the administrator and loaded at boot. All security-relevant, kernel-level access operations on the system are intercepted by SELinux and examined in the context of the loaded security policy. If the loaded policy allows the operation, it continues. Otherwise, the operation is blocked and the process receives an error. + +SELinux decisions, such as allowing or disallowing access, are cached. This cache is known as the Access Vector Cache (AVC). When using these cached decisions, SELinux policy rules need to be checked less, which increases performance. Remember that SELinux policy rules have no effect if DAC rules deny access first. diff --git a/modules/ROOT/pages/_partials/2delete-con_selinux-examples.adoc b/modules/ROOT/pages/_partials/2delete-con_selinux-examples.adoc new file mode 100644 index 0000000..f5d5c42 --- /dev/null +++ b/modules/ROOT/pages/_partials/2delete-con_selinux-examples.adoc @@ -0,0 +1,19 @@ +// Module included in the following assemblies: +// +// getting-started-with-selinux.adoc +:experimental: + +[#{context}-selinux-examples] += SELinux examples + +The following examples demonstrate how SELinux increases security: + +* The default action is deny. If an SELinux policy rule does not exist to allow access, such as for a process opening a file, access is denied. + +* SELinux can confine Linux users. A number of confined SELinux users exist in SELinux policy. Linux users can be mapped to confined SELinux users to take advantage of the security rules and mechanisms applied to them. For example, mapping a Linux user to the SELinux `user_u` user, results in a Linux user that is not able to run (unless configured otherwise) set user ID (setuid) applications, such as [command]`sudo` and [command]`su`, as well as preventing them from executing files and applications in their home directory. If configured, this prevents users from executing malicious files from their home directories. + +* Increased process and data separation. Processes run in their own domains, preventing processes from accessing files used by other processes, as well as preventing processes from accessing other processes. For example, when running SELinux, unless otherwise configured, an attacker cannot compromise a Samba server, and then use that Samba server as an attack vector to read and write to files used by other processes, such as MariaDB databases. + +* SELinux helps mitigate the damage made by configuration mistakes. Domain Name System (DNS) servers often replicate information between each other in what is known as a zone transfer. Attackers can use zone transfers to update DNS servers with false information. When running the Berkeley Internet Name Domain (BIND) as a DNS server in Fedora, even if an administrator forgets to limit which servers can perform a zone transfer, the default SELinux policy prevents zone files footnote:[Text files that include information, such as host name to IP address mappings, that are used by DNS servers.] from being updated using zone transfers, by the BIND `named` daemon itself, and by other processes. + +* See the link:++https://www.networkworld.com++[NetworkWorld.com] article, link:++https://www.networkworld.com/article/2283723/lan-wan/a-seatbelt-for-server-software--selinux-blocks-real-world-exploits.html++[A seatbelt for server software: SELinux blocks real-world exploits]footnote:[Marti, Don. "A seatbelt for server software: SELinux blocks real-world exploits". Published 24 February 2008. Accessed 27 August 2009: link:++https://www.networkworld.com/article/2283723/lan-wan/a-seatbelt-for-server-software--selinux-blocks-real-world-exploits.html++[].], for background information about SELinux, and information about various exploits that SELinux has prevented. diff --git a/modules/ROOT/pages/_partials/2delete-con_selinux-states-and-modes.adoc b/modules/ROOT/pages/_partials/2delete-con_selinux-states-and-modes.adoc new file mode 100644 index 0000000..b83bc04 --- /dev/null +++ b/modules/ROOT/pages/_partials/2delete-con_selinux-states-and-modes.adoc @@ -0,0 +1,47 @@ +// Module included in the following assemblies: +// +// getting-started-with-selinux.adoc +:experimental: + +[#{context}-selinux-states-and-modes] += SELinux states and modes + +SELinux can run in one of three modes: disabled, permissive, or enforcing. + +Disabled mode is strongly discouraged; not only does the system avoid enforcing the SELinux policy, it also avoids labeling any persistent objects such as files, making it difficult to enable SELinux in the future. + +In permissive mode, the system acts as if SELinux is enforcing the loaded security policy, including labeling objects and emitting access denial entries in the logs, but it does not actually deny any operations. While not recommended for production systems, permissive mode can be helpful for SELinux policy development. + +Enforcing mode is the default, and recommended, mode of operation; in enforcing mode SELinux operates normally, enforcing the loaded security policy on the entire system. + +Use the [command]`setenforce` utility to change between enforcing and permissive mode. Changes made with [command]`setenforce` do not persist across reboots. To change to enforcing mode, enter the [command]`setenforce 1` command as the Linux root user. To change to permissive mode, enter the [command]`setenforce 0` command. Use the [command]`getenforce` utility to view the current SELinux mode: + +---- +~]# getenforce +Enforcing +---- + +---- +~]# setenforce 0 +~]# getenforce +Permissive +---- + +---- +~]# setenforce 1 +~]# getenforce +Enforcing +---- + +In Fedora, you can set individual domains to permissive mode while the system runs in enforcing mode. For example, to make the `httpd_t` domain permissive: + +---- +~]# semanage permissive -a httpd_t +---- + +// See <> for more information. + +// [NOTE] +// ==== +// Persistent states and modes changes are covered in <>. +// ==== diff --git a/modules/ROOT/pages/_partials/con_benefits-of-selinux.adoc b/modules/ROOT/pages/_partials/con_benefits-of-selinux.adoc deleted file mode 100644 index 4f32531..0000000 --- a/modules/ROOT/pages/_partials/con_benefits-of-selinux.adoc +++ /dev/null @@ -1,29 +0,0 @@ -// Module included in the following assemblies: -// -// getting-started-with-selinux.adoc -:experimental: - -[#{context}-benefits-of-selinux] -= Benefits of running SELinux - -SELinux provides the following benefits: - -* All processes and files are labeled. SELinux policy rules define how processes interact with files, as well as how processes interact with each other. Access is only allowed if an SELinux policy rule exists that specifically allows it. - -* Fine-grained access control. Stepping beyond traditional UNIX permissions that are controlled at user discretion and based on Linux user and group IDs, SELinux access decisions are based on all available information, such as an SELinux user, role, type, and, optionally, a security level. - -* SELinux policy is administratively-defined and enforced system-wide. - -* Improved mitigation for privilege escalation attacks. Processes run in domains, and are therefore separated from each other. SELinux policy rules define how processes access files and other processes. If a process is compromised, the attacker only has access to the normal functions of that process, and to files the process has been configured to have access to. For example, if the Apache HTTP Server is compromised, an attacker cannot use that process to read files in user home directories, unless a specific SELinux policy rule was added or configured to allow such access. - -* SELinux can be used to enforce data confidentiality and integrity, as well as protecting processes from untrusted inputs. - -However, SELinux is not: - -* antivirus software, - -* replacement for passwords, firewalls, and other security systems, - -* all-in-one security solution. - -SELinux is designed to enhance existing security solutions, not replace them. Even when running SELinux, it is important to continue to follow good security practices, such as keeping software up-to-date, using hard-to-guess passwords, or firewalls. diff --git a/modules/ROOT/pages/_partials/con_introduction-to-selinux.adoc b/modules/ROOT/pages/_partials/con_introduction-to-selinux.adoc deleted file mode 100644 index 29a262a..0000000 --- a/modules/ROOT/pages/_partials/con_introduction-to-selinux.adoc +++ /dev/null @@ -1,39 +0,0 @@ -// Module included in the following assemblies: -// -// getting-started-with-selinux.adoc - -[#{context}-introduction-to-selinux] -= Introduction to SELinux - -Security Enhanced Linux (SELinux) provides an additional layer of system security. SELinux fundamentally answers the question: _May do to ?_, for example: _May a web server access files in users' home directories?_ - -The standard access policy based on the user, group, and other permissions, known as Discretionary Access Control (DAC), does not enable system administrators to create comprehensive and fine-grained security policies, such as restricting specific applications to only viewing log files, while allowing other applications to append new data to the log files. - -SELinux implements Mandatory Access Control (MAC). Every process and system resource has a special security label called a _SELinux context_. A SELinux context, sometimes referred to as a _SELinux label_, is an identifier which abstracts away the system-level details and focuses on the security properties of the entity. Not only does this provide a consistent way of referencing objects in the SELinux policy, but it also removes any ambiguity that can be found in other identification methods; for example, a file can have multiple valid path names on a system that makes use of bind mounts. - -The SELinux policy uses these contexts in a series of rules which define how processes can interact with each other and the various system resources. By default, the policy does not allow any interaction unless a rule explicitly grants access. - -[NOTE] -==== -It is important to remember that SELinux policy rules are checked after DAC rules. SELinux policy rules are not used if DAC rules deny access first, which means that no SELinux denial is logged if the traditional DAC rules prevent the access. -==== - -SELinux contexts have several fields: user, role, type, and security level. The SELinux type information is perhaps the most important when it comes to the SELinux policy, as the most common policy rule which defines the allowed interactions between processes and system resources uses SELinux types and not the full SELinux context. SELinux types usually end with `_t`. For example, the type name for the web server is `httpd_t`. The type context for files and directories normally found in `/var/www/html/` is `httpd_sys_content_t`. The type contexts for files and directories normally found in `/tmp` and `/var/tmp/` is `tmp_t`. The type context for web server ports is `http_port_t`. - -For example, there is a policy rule that permits Apache (the web server process running as `httpd_t`) to access files and directories with a context normally found in `/var/www/html/` and other web server directories (`httpd_sys_content_t`). There is no allow rule in the policy for files normally found in `/tmp` and `/var/tmp/`, so access is not permitted. With SELinux, even if Apache is compromised, and a malicious script gains access, it is still not able to access the `/tmp` directory. - -[#fig-intro-httpd-mysqld] -.SELinux allows the Apache process running as httpd_t to access the /var/www/html/ directory and it denies the same process to access the /data/mysql/ directory because there is no allow rule for the httpd_t and mysqld_db_t type contexts). On the other hand, the MariaDB process running as mysqld_t is able to access the /data/mysql/ directory and SELinux also correctly denies the process with the mysqld_t type to access the /var/www/html/ directory labeled as httpd_sys_content_t. -image::selinux-intro-apache-mariadb.png[SELinux_Apache_MariaDB_example] - -[discrete] -== Additional resources -To better understand SELinux basic concepts, see the following documentation: - -* link:++https://people.redhat.com/duffy/selinux/selinux-coloring-book_A4-Stapled.pdf++[The SELinux Coloring Book] - -* link:++https://people.redhat.com/tcameron/Summit2012/SELinux/cameron_w_120_selinux_for_mere_mortals.pdf++[SELinux for Mere Mortals] - -* link:++http://selinuxproject.org/page/FAQ++[SELinux Wiki FAQ] - -* link:++http://freecomputerbooks.com/books/The_SELinux_Notebook-4th_Edition.pdf++[The SELinux Notebook] diff --git a/modules/ROOT/pages/_partials/con_selinux-architecture.adoc b/modules/ROOT/pages/_partials/con_selinux-architecture.adoc deleted file mode 100644 index f636ef8..0000000 --- a/modules/ROOT/pages/_partials/con_selinux-architecture.adoc +++ /dev/null @@ -1,11 +0,0 @@ -// Module included in the following assemblies: -// -// getting-started-with-selinux.adoc -:experimental: - -[#{context}-selinux-architecture] -= SELinux architecture - -SELinux is a Linux Security Module (LSM) that is built into the Linux kernel. The SELinux subsystem in the kernel is driven by a security policy which is controlled by the administrator and loaded at boot. All security-relevant, kernel-level access operations on the system are intercepted by SELinux and examined in the context of the loaded security policy. If the loaded policy allows the operation, it continues. Otherwise, the operation is blocked and the process receives an error. - -SELinux decisions, such as allowing or disallowing access, are cached. This cache is known as the Access Vector Cache (AVC). When using these cached decisions, SELinux policy rules need to be checked less, which increases performance. Remember that SELinux policy rules have no effect if DAC rules deny access first. diff --git a/modules/ROOT/pages/_partials/con_selinux-examples.adoc b/modules/ROOT/pages/_partials/con_selinux-examples.adoc deleted file mode 100644 index f5d5c42..0000000 --- a/modules/ROOT/pages/_partials/con_selinux-examples.adoc +++ /dev/null @@ -1,19 +0,0 @@ -// Module included in the following assemblies: -// -// getting-started-with-selinux.adoc -:experimental: - -[#{context}-selinux-examples] -= SELinux examples - -The following examples demonstrate how SELinux increases security: - -* The default action is deny. If an SELinux policy rule does not exist to allow access, such as for a process opening a file, access is denied. - -* SELinux can confine Linux users. A number of confined SELinux users exist in SELinux policy. Linux users can be mapped to confined SELinux users to take advantage of the security rules and mechanisms applied to them. For example, mapping a Linux user to the SELinux `user_u` user, results in a Linux user that is not able to run (unless configured otherwise) set user ID (setuid) applications, such as [command]`sudo` and [command]`su`, as well as preventing them from executing files and applications in their home directory. If configured, this prevents users from executing malicious files from their home directories. - -* Increased process and data separation. Processes run in their own domains, preventing processes from accessing files used by other processes, as well as preventing processes from accessing other processes. For example, when running SELinux, unless otherwise configured, an attacker cannot compromise a Samba server, and then use that Samba server as an attack vector to read and write to files used by other processes, such as MariaDB databases. - -* SELinux helps mitigate the damage made by configuration mistakes. Domain Name System (DNS) servers often replicate information between each other in what is known as a zone transfer. Attackers can use zone transfers to update DNS servers with false information. When running the Berkeley Internet Name Domain (BIND) as a DNS server in Fedora, even if an administrator forgets to limit which servers can perform a zone transfer, the default SELinux policy prevents zone files footnote:[Text files that include information, such as host name to IP address mappings, that are used by DNS servers.] from being updated using zone transfers, by the BIND `named` daemon itself, and by other processes. - -* See the link:++https://www.networkworld.com++[NetworkWorld.com] article, link:++https://www.networkworld.com/article/2283723/lan-wan/a-seatbelt-for-server-software--selinux-blocks-real-world-exploits.html++[A seatbelt for server software: SELinux blocks real-world exploits]footnote:[Marti, Don. "A seatbelt for server software: SELinux blocks real-world exploits". Published 24 February 2008. Accessed 27 August 2009: link:++https://www.networkworld.com/article/2283723/lan-wan/a-seatbelt-for-server-software--selinux-blocks-real-world-exploits.html++[].], for background information about SELinux, and information about various exploits that SELinux has prevented. diff --git a/modules/ROOT/pages/_partials/con_selinux-states-and-modes.adoc b/modules/ROOT/pages/_partials/con_selinux-states-and-modes.adoc deleted file mode 100644 index b83bc04..0000000 --- a/modules/ROOT/pages/_partials/con_selinux-states-and-modes.adoc +++ /dev/null @@ -1,47 +0,0 @@ -// Module included in the following assemblies: -// -// getting-started-with-selinux.adoc -:experimental: - -[#{context}-selinux-states-and-modes] -= SELinux states and modes - -SELinux can run in one of three modes: disabled, permissive, or enforcing. - -Disabled mode is strongly discouraged; not only does the system avoid enforcing the SELinux policy, it also avoids labeling any persistent objects such as files, making it difficult to enable SELinux in the future. - -In permissive mode, the system acts as if SELinux is enforcing the loaded security policy, including labeling objects and emitting access denial entries in the logs, but it does not actually deny any operations. While not recommended for production systems, permissive mode can be helpful for SELinux policy development. - -Enforcing mode is the default, and recommended, mode of operation; in enforcing mode SELinux operates normally, enforcing the loaded security policy on the entire system. - -Use the [command]`setenforce` utility to change between enforcing and permissive mode. Changes made with [command]`setenforce` do not persist across reboots. To change to enforcing mode, enter the [command]`setenforce 1` command as the Linux root user. To change to permissive mode, enter the [command]`setenforce 0` command. Use the [command]`getenforce` utility to view the current SELinux mode: - ----- -~]# getenforce -Enforcing ----- - ----- -~]# setenforce 0 -~]# getenforce -Permissive ----- - ----- -~]# setenforce 1 -~]# getenforce -Enforcing ----- - -In Fedora, you can set individual domains to permissive mode while the system runs in enforcing mode. For example, to make the `httpd_t` domain permissive: - ----- -~]# semanage permissive -a httpd_t ----- - -// See <> for more information. - -// [NOTE] -// ==== -// Persistent states and modes changes are covered in <>. -// ==== diff --git a/modules/ROOT/pages/changing-selinux-states-and-modes.adoc b/modules/ROOT/pages/changing-selinux-states-and-modes.adoc deleted file mode 100644 index 0c3cf11..0000000 --- a/modules/ROOT/pages/changing-selinux-states-and-modes.adoc +++ /dev/null @@ -1,355 +0,0 @@ -= Changing SELinux States and Modes - The Fedora Docs Team -:revnumber: F36 and newer -:revdate: 2023-08-09 -:category: Administration -:tags: How-to Security SELinux -//:imagesdir: ./images - - -// NOTE (TODO): several links (URLs) in the included modules could be replaced with URLs when the appropriate docs become available on fp.org - -//include::{partialsdir}/unreviewed-message.adoc[] - -//include::{partialsdir}/con_permanent-changes-in-selinux-states-and-modes.adoc[leveloffset=+1] -// Module included in the following assemblies: -// -// changing-selinux-states-and-modes.adoc - -== Permanent changes in SELinux states and modes - -As discussed in link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/selinux_users_and_administrators_guide/chap-security-enhanced_linux-introduction[Introduction to SELinux], SELinux can be enabled or disabled. When enabled, SELinux has two modes: enforcing and permissive. - -Use the [command]`getenforce` or [command]`sestatus` commands to check in which mode SELinux is running. The [command]`getenforce` command returns `Enforcing`, `Permissive`, or `Disabled`. - -The [command]`sestatus` command returns the SELinux status and the SELinux policy being used: - -[source,bash] ----- -[~]$ sestatus -SELinux status: enabled -SELinuxfs mount: /sys/fs/selinux -SELinux root directory: /etc/selinux -Loaded policy name: targeted -Current mode: enforcing -Mode from config file: enforcing -Policy MLS status: enabled -Policy deny_unknown status: allowed -Memory protection checking: actual (secure) -Max kernel policy version: 31 ----- - -[NOTE] -==== -When systems run SELinux in permissive mode, users and processes can label various file-system objects incorrectly. File-system objects created while SELinux is disabled are not labeled at all. This behavior causes problems when changing to enforcing mode because SELinux relies on correct labels of file-system objects. - -To prevent incorrectly labeled and unlabeled files from causing problems, file systems are automatically relabeled when changing from the disabled state to permissive or enforcing mode. In permissive mode, use the [command]`fixfiles -F onboot` command as root to create `/.autorelabel` file containing the `-F` option to ensure that files are relabeled upon next reboot. -==== - - -//include::{partialsdir}/proc_enabling-selinux.adoc[leveloffset=+1] -// Module included in the following assemblies: -// -// changing-selinux-states-and-modes.adoc - -== Enabling SELinux - -When enabled, SELinux can run in one of two modes: enforcing or permissive. The following sections show how to permanently change into these modes. - -While enabling SELinux on systems that previously had it disabled, to avoid problems, such as systems unable to boot or process failures, follow this procedure. - -.Prerequisites - -* The [package]`selinux-policy-targeted`, [package]`selinux-policy`, [package]`libselinux-utils`, and [package]`grubby` packages are installed. To check that a particular package is installed: -+ -[subs="quotes"] ----- -$ *rpm -q _package_name_* ----- - -.Procedure - -. If your system has SELinux disabled at the kernel level (this is the recommended way, see xref:changing-selinux-states-and-modes.adoc#_disabling_selinux[[]), change this first. Check if you have the `selinux=0` option in your kernel command line: -+ -[subs="quotes"] ----- -$ *cat /proc/cmdline* -BOOT_IMAGE=... ... selinux=0 ----- - -.. Remove the `selinux=0` option from the bootloader configuration using [command]`grubby`: -+ -[subs="quotes"] ----- -$ *sudo grubby --update-kernel ALL --remove-args selinux* ----- - -.. The change applies after you restart the system in one of the following steps. - -. Ensure the file system is relabeled on the next boot: -+ -[subs="quotes"] ----- -$ *sudo fixfiles onboot* ----- - -. Enable SELinux in permissive mode. For more information, see xref:changing-selinux-states-and-modes.adoc#_changing_to_permissive_mode[]. - -. Restart your system: -+ -[subs="quotes"] ----- -$ *reboot* ----- - -. Check for SELinux denial messages. -+ -[subs="quotes"] ----- -$ *sudo ausearch -m AVC,USER_AVC,SELINUX_ERR,USER_SELINUX_ERR -ts recent* ----- - -. If there are no denials, switch to enforcing mode. For more information, see xref:changing-selinux-states-and-modes.adoc#_changing_to_enforcing_mode[]. - -To run custom applications with SELinux in enforcing mode, choose one of the following scenarios: - -* Run your application in the `unconfined_service_t` domain. -// See <> for more information. - -* Write a new policy for your application. See the link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/using_selinux/writing-a-custom-selinux-policy_using-selinux[Writing a custom SELinux policy] chapter in the link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/using_selinux/index[RHEL 8 Using SELinux] document for more information. - - - -//include::{partialsdir}/proc_changing-to-permissive-mode.adoc[leveloffset=+2] -// Module included in the following assemblies: -// -// assembly_changing-selinux-states-and-modes.adoc - -=== Changing to permissive mode - -Use the following procedure to permanently change SELinux mode to permissive. When SELinux is running in permissive mode, SELinux policy is not enforced. The system remains operational and SELinux does not deny any operations but only logs AVC messages, which can be then used for troubleshooting, debugging, and SELinux policy improvements. Each AVC is logged only once in this case. - -.Prerequisites - -* The `selinux-policy-targeted`, `libselinux-utils`, and `policycoreutils` packages are installed on your system. -* The `selinux=0` or `enforcing=0` kernel parameters are not used. - -.Procedure - -. Open the `/etc/selinux/config` file in a text editor of your choice, for example: - ----- -# vi /etc/selinux/config ----- - -. Configure the `SELINUX=permissive` option: -[subs="quotes"] ----- -# This file controls the state of SELinux on the system. -# SELINUX= can take one of these three values: -# enforcing - SELinux security policy is enforced. -# permissive - SELinux prints warnings instead of enforcing. -# disabled - No SELinux policy is loaded. -SELINUX=*permissive* -# SELINUXTYPE= can take one of these two values: -# targeted - Targeted processes are protected, -# mls - Multi Level Security protection. -SELINUXTYPE=targeted ----- - -. Restart the system: -+ -[subs="quotes"] ----- -# *reboot* ----- - - - -/include::{partialsdir}/proc_changing-to-enforcing-mode.adoc[leveloffset=+2] -// Module included in the following assemblies: -// -// changing-selinux-states-and-modes.adoc - -=== Changing to enforcing mode - -Use the following procedure to switch SELinux to enforcing mode. When SELinux is running in enforcing mode, it enforces the SELinux policy and denies access based on SELinux policy rules. In Fedora, enforcing mode is enabled by default when the system was initially installed with SELinux. - -.Prerequisites - -* The `selinux-policy-targeted`, `libselinux-utils`, and `policycoreutils` packages are installed on your system. - -* The `selinux=0` or `enforcing=0` kernel parameters are not used. - -.Procedure - -. Open the `/etc/selinux/config` file in a text editor of your choice, for example: -+ ----- -# vi /etc/selinux/config ----- - -. Configure the `SELINUX=enforcing` option: -+ -[subs="quotes"] ----- -# This file controls the state of SELinux on the system. -# SELINUX= can take one of these three values: -# enforcing - SELinux security policy is enforced. -# permissive - SELinux prints warnings instead of enforcing. -# disabled - No SELinux policy is loaded. -SELINUX=*enforcing* -# SELINUXTYPE= can take one of these two values: -# targeted - Targeted processes are protected, -# mls - Multi Level Security protection. -SELINUXTYPE=targeted ----- - -. Save the change, and restart the system: -+ -[subs="quotes"] ----- -# reboot ----- -+ -On the next boot, SELinux relabels all the files and directories within the system and adds SELinux context for files and directories that were created when SELinux was disabled. - -.Verification - -. After the system restarts, confirm that the `getenforce` command returns `Enforcing`: -+ ----- -$ getenforce -Enforcing ----- - -[NOTE] -==== -After changing to enforcing mode, SELinux may deny some actions because of incorrect or missing SELinux policy rules. To view what actions SELinux denies, enter the following command as root: -[subs="quotes"] ----- -# ausearch -m AVC,USER_AVC,SELINUX_ERR,USER_SELINUX_ERR -ts today ----- -Alternatively, with the [package]`setroubleshoot-server` package installed, enter: -[subs="quotes"] ----- -# grep "SELinux is preventing" /var/log/messages ----- - -Standard users can use the GUI `setroubleshoot` to file bugs directly to Bugzilla. - -If SELinux is active and the Audit daemon (auditd) is not running on your system, then search for certain SELinux messages in the output of the dmesg command: ----- -# dmesg | grep -i -e type=1300 -e type=1400 ----- - -If SELinux denies some actions, see the link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/using_selinux/troubleshooting-problems-related-to-selinux_using-selinux[Troubleshooting problems related to SELinux] chapter in the link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/using_selinux/index[RHEL 8 Using SELinux] document for information about troubleshooting. -==== - - -//include::{partialsdir}/proc_disabling-selinux.adoc[leveloffset=+1] -// Module included in the following assemblies: -// -// changing-selinux-states-and-modes.adoc - -== Disabling SELinux - -Use the following procedure to permanently disable SELinux. - -[IMPORTANT] -==== -When SELinux is disabled, SELinux policy is not loaded at all; it is not enforced and AVC messages are not logged. Therefore, all benefits of running SELinux listed in xref:changing-selinux-states-and-modes.adoc#_benefits_of_selinux[Benefits of SELinux] are lost. - -It is recommended to use permissive mode instead of permanently disabling SELinux. See xref:changing-selinux-states-and-modes.adoc#_changing_to_permissive_mode[] for more information about permissive mode. -==== - -[WARNING] -==== -Disabling SELinux using the SELINUX=disabled option in the /etc/selinux/config results in a process in which the kernel boots with SELinux enabled and switches to disabled mode later in the boot process. Because memory leaks and race conditions causing kernel panics can occur, prefer disabling SELinux by adding the selinux=0 parameter to the kernel command line as described in Changing SELinux modes at boot time if your scenario really requires to completely disable SELinux. -==== - -.Prerequisites - -* The [package]`grubby` package is installed: -+ -[subs="quotes"] ----- -$ *rpm -q grubby* -grubby-_version_ ----- - -.Procedure - -. Open the `/etc/selinux/config` file in a text editor of your choice, for example: -+ -[subs="quotes"] ----- -# vi /etc/selinux/config ----- - -. Configure the SELINUX=disabled option: -+ -[subs="quotes"] ----- -# This file controls the state of SELinux on the system. -# SELINUX= can take one of these three values: -# enforcing - SELinux security policy is enforced. -# permissive - SELinux prints warnings instead of enforcing. -# disabled - No SELinux policy is loaded. -SELINUX=disabled -# SELINUXTYPE= can take one of these two values: -# targeted - Targeted processes are protected, -# mls - Multi Level Security protection. -SELINUXTYPE=targeted ----- - -. Save the change, and restart your system: ----- -# reboot ----- - -.Verification - -* After reboot, confirm that the [command]`getenforce` command returns `Disabled`: -+ -[subs="quotes"] ----- -$ *getenforce* -Disabled ----- - - -//include::{partialsdir}/ref_changing-selinux-modes-at-boot-time.adoc[leveloffset=+1] -// Module included in the following assemblies: -// -// assembly_changing-selinux-states-and-modes.adoc -== Changing SELinux Modes at Boot Time - -On boot, you can set several kernel parameters to change the way SELinux runs: - -enforcing=0:: Setting this parameter causes the system to start in permissive mode, which is useful when troubleshooting issues. Using permissive mode might be the only option to detect a problem if your file system is too corrupted. Moreover, in permissive mode, the system continues to create the labels correctly. The AVC messages that are created in this mode can be different than in enforcing mode. -+ -In permissive mode, only the first denial from a series of the same denials is reported. However, in enforcing mode, you might get a denial related to reading a directory, and an application stops. In permissive mode, you get the same AVC message, but the application continues reading files in the directory and you get an AVC for each denial in addition. - -selinux=0:: This parameter causes the kernel to not load any part of the SELinux infrastructure. The init scripts notice that the system booted with the [option]`selinux=0` parameter and touch the `/.autorelabel` file. This causes the system to automatically relabel the next time you boot with SELinux enabled. -+ -[IMPORTANT] -==== -Using the [option]`selinux=0` parameter is not recommended. To debug your system, prefer using permissive mode. -==== - -autorelabel=1:: This parameter forces the system to relabel similarly to the following commands: -+ ----- -# touch /.autorelabel -# reboot ----- -+ -If a file system contains a large amount of mislabeled objects, start the system in permissive mode to make the autorelabel process successful. - -For additional SELinux-related kernel boot parameters, such as [option]`checkreqprot`, see the `kernel-parameters.txt` file. This file is available in the source package of your Linux kernel (.src.rpm). To download the source package containing the currently used kernel: ----- -[~]# dnf download --source kernel ----- - - diff --git a/modules/ROOT/pages/getting-started-with-selinux.adoc b/modules/ROOT/pages/getting-started-with-selinux.adoc deleted file mode 100644 index 783865b..0000000 --- a/modules/ROOT/pages/getting-started-with-selinux.adoc +++ /dev/null @@ -1,21 +0,0 @@ -ifdef::context[:parent-context: {context}] -:context: getting-started-with-selinux -[id='getting-started-with-selinux-{context}'] -= Getting started with SELinux -:context: getting-started-with-selinux - -:md: en-US/modules -:imagesdir: ./images - -include::{partialsdir}/unreviewed-message.adoc[] - -:leveloffset: +1 -include::{partialsdir}/con_introduction-to-selinux.adoc[] -include::{partialsdir}/con_benefits-of-selinux.adoc[] -include::{partialsdir}/con_selinux-examples.adoc[] -include::{partialsdir}/con_selinux-architecture.adoc[] -include::{partialsdir}/con_selinux-states-and-modes.adoc[] -:leveloffset: -1 - -ifdef::parent-context[:context: {parent-context}] -ifndef::parent-context[:!context:] diff --git a/modules/ROOT/pages/selinux-changing-states-and-modes.adoc b/modules/ROOT/pages/selinux-changing-states-and-modes.adoc new file mode 100644 index 0000000..f1d8dd9 --- /dev/null +++ b/modules/ROOT/pages/selinux-changing-states-and-modes.adoc @@ -0,0 +1,322 @@ += Changing SELinux States and Modes + The Fedora Docs Team; Peter Boy (pboy) +:revnumber: F36 and newer +:revdate: 2023-08-09 +:category: SELinux +:tags: How-to Security SELinux +:page-aliases: changing-selinux-states-and-modes.adoc +//:imagesdir: ./images + + +// NOTE (TODO): several links (URLs) could be replaced with URLs when the appropriate docs become available on fp.org + + +== Permanent changes in SELinux states and modes + +As discussed in xref:selinux-getting-started.adoc#_SELinux_states_and_modes[Getting started with SELinux] SELinux can be enabled or disabled. When enabled, SELinux has two modes: enforcing and permissive. + +Use the [command]`getenforce` or [command]`sestatus` commands to check in which mode SELinux is running. The [command]`getenforce` command returns `Enforcing`, `Permissive`, or `Disabled`. + +The [command]`sestatus` command returns the SELinux status and the SELinux policy being used: + +[source,bash] +---- +[~]$ sestatus +SELinux status: enabled +SELinuxfs mount: /sys/fs/selinux +SELinux root directory: /etc/selinux +Loaded policy name: targeted +Current mode: enforcing +Mode from config file: enforcing +Policy MLS status: enabled +Policy deny_unknown status: allowed +Memory protection checking: actual (secure) +Max kernel policy version: 31 +---- + +[NOTE] +==== +When systems run SELinux in permissive mode, users and processes can label various file-system objects incorrectly. File-system objects created while SELinux is disabled are not labeled at all. This behavior causes problems when changing to enforcing mode because SELinux relies on correct labels of file-system objects. + +To prevent incorrectly labeled and unlabeled files from causing problems, file systems are automatically relabeled when changing from the disabled state to permissive or enforcing mode. In permissive mode, use the [command]`fixfiles -F onboot` command as root to create `/.autorelabel` file containing the `-F` option to ensure that files are relabeled upon next reboot. +==== + + +== Enabling SELinux + +When enabled, SELinux can run in one of two modes: enforcing or permissive. The following sections show how to permanently change into these modes. + +While enabling SELinux on systems that previously had it disabled, to avoid problems, such as systems unable to boot or process failures, follow this procedure. + +.Prerequisites + +* The [package]`selinux-policy-targeted`, [package]`selinux-policy`, [package]`libselinux-utils`, and [package]`grubby` packages are installed. To check that a particular package is installed: ++ +[subs="quotes"] +---- +$ *rpm -q _package_name_* +---- + +.Procedure + +. If your system has SELinux disabled at the kernel level (this is the recommended way, see xref:changing-selinux-states-and-modes.adoc#_disabling_selinux[[]), change this first. Check if you have the `selinux=0` option in your kernel command line: ++ +[subs="quotes"] +---- +$ *cat /proc/cmdline* +BOOT_IMAGE=... ... selinux=0 +---- + +.. Remove the `selinux=0` option from the bootloader configuration using [command]`grubby`: ++ +[subs="quotes"] +---- +$ *sudo grubby --update-kernel ALL --remove-args selinux* +---- + +.. The change applies after you restart the system in one of the following steps. + +. Ensure the file system is relabeled on the next boot: ++ +[subs="quotes"] +---- +$ *sudo fixfiles onboot* +---- + +. Enable SELinux in permissive mode. For more information, see xref:changing-selinux-states-and-modes.adoc#_changing_to_permissive_mode[]. + +. Restart your system: ++ +[subs="quotes"] +---- +$ *reboot* +---- + +. Check for SELinux denial messages. ++ +[subs="quotes"] +---- +$ *sudo ausearch -m AVC,USER_AVC,SELINUX_ERR,USER_SELINUX_ERR -ts recent* +---- + +. If there are no denials, switch to enforcing mode. For more information, see xref:changing-selinux-states-and-modes.adoc#_changing_to_enforcing_mode[]. + +To run custom applications with SELinux in enforcing mode, choose one of the following scenarios: + +* Run your application in the `unconfined_service_t` domain. +// See <> for more information. + +* Write a new policy for your application. See the link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/using_selinux/writing-a-custom-selinux-policy_using-selinux[Writing a custom SELinux policy] chapter in the link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/using_selinux/index[RHEL 8 Using SELinux] document for more information. + + +=== Changing to permissive mode + +Use the following procedure to permanently change SELinux mode to permissive. When SELinux is running in permissive mode, SELinux policy is not enforced. The system remains operational and SELinux does not deny any operations but only logs AVC messages, which can be then used for troubleshooting, debugging, and SELinux policy improvements. Each AVC is logged only once in this case. + +.Prerequisites + +* The `selinux-policy-targeted`, `libselinux-utils`, and `policycoreutils` packages are installed on your system. +* The `selinux=0` or `enforcing=0` kernel parameters are not used. + +.Procedure + +. Open the `/etc/selinux/config` file in a text editor of your choice, for example: + +---- +# vi /etc/selinux/config +---- + +. Configure the `SELINUX=permissive` option: +[subs="quotes"] +---- +# This file controls the state of SELinux on the system. +# SELINUX= can take one of these three values: +# enforcing - SELinux security policy is enforced. +# permissive - SELinux prints warnings instead of enforcing. +# disabled - No SELinux policy is loaded. +SELINUX=*permissive* +# SELINUXTYPE= can take one of these two values: +# targeted - Targeted processes are protected, +# mls - Multi Level Security protection. +SELINUXTYPE=targeted +---- + +. Restart the system: ++ +[subs="quotes"] +---- +# *reboot* +---- + + +=== Changing to enforcing mode + +Use the following procedure to switch SELinux to enforcing mode. When SELinux is running in enforcing mode, it enforces the SELinux policy and denies access based on SELinux policy rules. In Fedora, enforcing mode is enabled by default when the system was initially installed with SELinux. + +.Prerequisites + +* The `selinux-policy-targeted`, `libselinux-utils`, and `policycoreutils` packages are installed on your system. + +* The `selinux=0` or `enforcing=0` kernel parameters are not used. + +.Procedure + +. Open the `/etc/selinux/config` file in a text editor of your choice, for example: ++ +---- +# vi /etc/selinux/config +---- + +. Configure the `SELINUX=enforcing` option: ++ +[subs="quotes"] +---- +# This file controls the state of SELinux on the system. +# SELINUX= can take one of these three values: +# enforcing - SELinux security policy is enforced. +# permissive - SELinux prints warnings instead of enforcing. +# disabled - No SELinux policy is loaded. +SELINUX=*enforcing* +# SELINUXTYPE= can take one of these two values: +# targeted - Targeted processes are protected, +# mls - Multi Level Security protection. +SELINUXTYPE=targeted +---- + +. Save the change, and restart the system: ++ +[subs="quotes"] +---- +# reboot +---- ++ +On the next boot, SELinux relabels all the files and directories within the system and adds SELinux context for files and directories that were created when SELinux was disabled. + +.Verification + +. After the system restarts, confirm that the `getenforce` command returns `Enforcing`: ++ +---- +$ getenforce +Enforcing +---- + +[NOTE] +==== +After changing to enforcing mode, SELinux may deny some actions because of incorrect or missing SELinux policy rules. To view what actions SELinux denies, enter the following command as root: +[subs="quotes"] +---- +# ausearch -m AVC,USER_AVC,SELINUX_ERR,USER_SELINUX_ERR -ts today +---- +Alternatively, with the [package]`setroubleshoot-server` package installed, enter: +[subs="quotes"] +---- +# grep "SELinux is preventing" /var/log/messages +---- + +Standard users can use the GUI `setroubleshoot` to file bugs directly to Bugzilla. + +If SELinux is active and the Audit daemon (auditd) is not running on your system, then search for certain SELinux messages in the output of the dmesg command: +---- +# dmesg | grep -i -e type=1300 -e type=1400 +---- + +If SELinux denies some actions, see the link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/using_selinux/troubleshooting-problems-related-to-selinux_using-selinux[Troubleshooting problems related to SELinux] chapter in the link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/using_selinux/index[RHEL 8 Using SELinux] document for information about troubleshooting. +==== + + +== Disabling SELinux + +Use the following procedure to permanently disable SELinux. + +[IMPORTANT] +==== +When SELinux is disabled, SELinux policy is not loaded at all; it is not enforced and AVC messages are not logged. Therefore, all benefits of running SELinux listed in xref:changing-selinux-states-and-modes.adoc#_benefits_of_selinux[Benefits of SELinux] are lost. + +It is recommended to use permissive mode instead of permanently disabling SELinux. See xref:changing-selinux-states-and-modes.adoc#_changing_to_permissive_mode[] for more information about permissive mode. +==== + +[WARNING] +==== +Disabling SELinux using the SELINUX=disabled option in the /etc/selinux/config results in a process in which the kernel boots with SELinux enabled and switches to disabled mode later in the boot process. Because memory leaks and race conditions causing kernel panics can occur, prefer disabling SELinux by adding the selinux=0 parameter to the kernel command line as described in Changing SELinux modes at boot time if your scenario really requires to completely disable SELinux. +==== + +.Prerequisites + +* The [package]`grubby` package is installed: ++ +[subs="quotes"] +---- +$ *rpm -q grubby* +grubby-_version_ +---- + +.Procedure + +. Open the `/etc/selinux/config` file in a text editor of your choice, for example: ++ +[subs="quotes"] +---- +# vi /etc/selinux/config +---- + +. Configure the SELINUX=disabled option: ++ +[subs="quotes"] +---- +# This file controls the state of SELinux on the system. +# SELINUX= can take one of these three values: +# enforcing - SELinux security policy is enforced. +# permissive - SELinux prints warnings instead of enforcing. +# disabled - No SELinux policy is loaded. +SELINUX=disabled +# SELINUXTYPE= can take one of these two values: +# targeted - Targeted processes are protected, +# mls - Multi Level Security protection. +SELINUXTYPE=targeted +---- + +. Save the change, and restart your system: +---- +# reboot +---- + +.Verification + +* After reboot, confirm that the [command]`getenforce` command returns `Disabled`: ++ +[subs="quotes"] +---- +$ *getenforce* +Disabled +---- + + +== Changing SELinux Modes at Boot Time + +On boot, you can set several kernel parameters to change the way SELinux runs: + +enforcing=0:: Setting this parameter causes the system to start in permissive mode, which is useful when troubleshooting issues. Using permissive mode might be the only option to detect a problem if your file system is too corrupted. Moreover, in permissive mode, the system continues to create the labels correctly. The AVC messages that are created in this mode can be different than in enforcing mode. ++ +In permissive mode, only the first denial from a series of the same denials is reported. However, in enforcing mode, you might get a denial related to reading a directory, and an application stops. In permissive mode, you get the same AVC message, but the application continues reading files in the directory and you get an AVC for each denial in addition. + +selinux=0:: This parameter causes the kernel to not load any part of the SELinux infrastructure. The init scripts notice that the system booted with the [option]`selinux=0` parameter and touch the `/.autorelabel` file. This causes the system to automatically relabel the next time you boot with SELinux enabled. ++ +[IMPORTANT] +==== +Using the [option]`selinux=0` parameter is not recommended. To debug your system, prefer using permissive mode. +==== + +autorelabel=1:: This parameter forces the system to relabel similarly to the following commands: ++ +---- +# touch /.autorelabel +# reboot +---- ++ +If a file system contains a large amount of mislabeled objects, start the system in permissive mode to make the autorelabel process successful. + +For additional SELinux-related kernel boot parameters, such as [option]`checkreqprot`, see the `kernel-parameters.txt` file. This file is available in the source package of your Linux kernel (.src.rpm). To download the source package containing the currently used kernel: +---- +[~]# dnf download --source kernel +---- diff --git a/modules/ROOT/pages/selinux-getting-started.adoc b/modules/ROOT/pages/selinux-getting-started.adoc new file mode 100644 index 0000000..aec926c --- /dev/null +++ b/modules/ROOT/pages/selinux-getting-started.adoc @@ -0,0 +1,131 @@ += Getting started with SELinux +The Fedora Docs Team; Peter Boy (pboy) +:revnumber: F35-F38 +:revdate: 2023-09-08 +:category: SELinux +:tags: How-to Security SELinux +:page-aliases: getting-started-with-selinux.adoc +//:imagesdir: ./images + +== Introduction to SELinux + +Security Enhanced Linux (SELinux) provides an additional layer of system security. SELinux fundamentally answers the question: _May do to ?_, for example: _May a web server access files in users' home directories?_ + +The standard access policy based on the user, group, and other permissions, known as Discretionary Access Control (DAC), does not enable system administrators to create comprehensive and fine-grained security policies, such as restricting specific applications to only viewing log files, while allowing other applications to append new data to the log files. + +SELinux implements Mandatory Access Control (MAC). Every process and system resource has a special security label called a _SELinux context_. A SELinux context, sometimes referred to as a _SELinux label_, is an identifier which abstracts away the system-level details and focuses on the security properties of the entity. Not only does this provide a consistent way of referencing objects in the SELinux policy, but it also removes any ambiguity that can be found in other identification methods; for example, a file can have multiple valid path names on a system that makes use of bind mounts. + +The SELinux policy uses these contexts in a series of rules which define how processes can interact with each other and the various system resources. By default, the policy does not allow any interaction unless a rule explicitly grants access. + +[NOTE] +==== +It is important to remember that SELinux policy rules are checked after DAC rules. SELinux policy rules are not used if DAC rules deny access first, which means that no SELinux denial is logged if the traditional DAC rules prevent the access. +==== + +SELinux contexts have several fields: user, role, type, and security level. The SELinux type information is perhaps the most important when it comes to the SELinux policy, as the most common policy rule which defines the allowed interactions between processes and system resources uses SELinux types and not the full SELinux context. SELinux types usually end with `_t`. For example, the type name for the web server is `httpd_t`. The type context for files and directories normally found in `/var/www/html/` is `httpd_sys_content_t`. The type contexts for files and directories normally found in `/tmp` and `/var/tmp/` is `tmp_t`. The type context for web server ports is `http_port_t`. + +For example, there is a policy rule that permits Apache (the web server process running as `httpd_t`) to access files and directories with a context normally found in `/var/www/html/` and other web server directories (`httpd_sys_content_t`). There is no allow rule in the policy for files normally found in `/tmp` and `/var/tmp/`, so access is not permitted. With SELinux, even if Apache is compromised, and a malicious script gains access, it is still not able to access the `/tmp` directory. + +[#fig-intro-httpd-mysqld] +.SELinux allows the Apache process running as httpd_t to access the /var/www/html/ directory and it denies the same process to access the /data/mysql/ directory because there is no allow rule for the httpd_t and mysqld_db_t type contexts). On the other hand, the MariaDB process running as mysqld_t is able to access the /data/mysql/ directory and SELinux also correctly denies the process with the mysqld_t type to access the /var/www/html/ directory labeled as httpd_sys_content_t. +image::selinux-intro-apache-mariadb.png[SELinux_Apache_MariaDB_example] + +[discrete] +=== Additional resources +To better understand SELinux basic concepts, see the following documentation: + +* link:++https://people.redhat.com/duffy/selinux/selinux-coloring-book_A4-Stapled.pdf++[The SELinux Coloring Book] + +* link:++https://people.redhat.com/tcameron/Summit2012/SELinux/cameron_w_120_selinux_for_mere_mortals.pdf++[SELinux for Mere Mortals] + +* link:++http://selinuxproject.org/page/FAQ++[SELinux Wiki FAQ] + +* link:++http://freecomputerbooks.com/books/The_SELinux_Notebook-4th_Edition.pdf++[The SELinux Notebook] + + +== Benefits of running SELinux + +SELinux provides the following benefits: + +* All processes and files are labeled. SELinux policy rules define how processes interact with files, as well as how processes interact with each other. Access is only allowed if an SELinux policy rule exists that specifically allows it. + +* Fine-grained access control. Stepping beyond traditional UNIX permissions that are controlled at user discretion and based on Linux user and group IDs, SELinux access decisions are based on all available information, such as an SELinux user, role, type, and, optionally, a security level. + +* SELinux policy is administratively-defined and enforced system-wide. + +* Improved mitigation for privilege escalation attacks. Processes run in domains, and are therefore separated from each other. SELinux policy rules define how processes access files and other processes. If a process is compromised, the attacker only has access to the normal functions of that process, and to files the process has been configured to have access to. For example, if the Apache HTTP Server is compromised, an attacker cannot use that process to read files in user home directories, unless a specific SELinux policy rule was added or configured to allow such access. + +* SELinux can be used to enforce data confidentiality and integrity, as well as protecting processes from untrusted inputs. + +However, SELinux is not: + +* antivirus software, + +* replacement for passwords, firewalls, and other security systems, + +* all-in-one security solution. + +SELinux is designed to enhance existing security solutions, not replace them. Even when running SELinux, it is important to continue to follow good security practices, such as keeping software up-to-date, using hard-to-guess passwords, or firewalls. + + +== SELinux examples + +The following examples demonstrate how SELinux increases security: + +* The default action is deny. If an SELinux policy rule does not exist to allow access, such as for a process opening a file, access is denied. + +* SELinux can confine Linux users. A number of confined SELinux users exist in SELinux policy. Linux users can be mapped to confined SELinux users to take advantage of the security rules and mechanisms applied to them. For example, mapping a Linux user to the SELinux `user_u` user, results in a Linux user that is not able to run (unless configured otherwise) set user ID (setuid) applications, such as [command]`sudo` and [command]`su`, as well as preventing them from executing files and applications in their home directory. If configured, this prevents users from executing malicious files from their home directories. + +* Increased process and data separation. Processes run in their own domains, preventing processes from accessing files used by other processes, as well as preventing processes from accessing other processes. For example, when running SELinux, unless otherwise configured, an attacker cannot compromise a Samba server, and then use that Samba server as an attack vector to read and write to files used by other processes, such as MariaDB databases. + +* SELinux helps mitigate the damage made by configuration mistakes. Domain Name System (DNS) servers often replicate information between each other in what is known as a zone transfer. Attackers can use zone transfers to update DNS servers with false information. When running the Berkeley Internet Name Domain (BIND) as a DNS server in Fedora, even if an administrator forgets to limit which servers can perform a zone transfer, the default SELinux policy prevents zone files footnote:[Text files that include information, such as host name to IP address mappings, that are used by DNS servers.] from being updated using zone transfers, by the BIND `named` daemon itself, and by other processes. + +* See the link:++https://www.networkworld.com++[NetworkWorld.com] article, link:++https://www.networkworld.com/article/2283723/lan-wan/a-seatbelt-for-server-software--selinux-blocks-real-world-exploits.html++[A seatbelt for server software: SELinux blocks real-world exploits]footnote:[Marti, Don. "A seatbelt for server software: SELinux blocks real-world exploits". Published 24 February 2008. Accessed 27 August 2009: link:++https://www.networkworld.com/article/2283723/lan-wan/a-seatbelt-for-server-software--selinux-blocks-real-world-exploits.html++[].], for background information about SELinux, and information about various exploits that SELinux has prevented. + + +== SELinux architecture + +SELinux is a Linux Security Module (LSM) that is built into the Linux kernel. The SELinux subsystem in the kernel is driven by a security policy which is controlled by the administrator and loaded at boot. All security-relevant, kernel-level access operations on the system are intercepted by SELinux and examined in the context of the loaded security policy. If the loaded policy allows the operation, it continues. Otherwise, the operation is blocked and the process receives an error. + +SELinux decisions, such as allowing or disallowing access, are cached. This cache is known as the Access Vector Cache (AVC). When using these cached decisions, SELinux policy rules need to be checked less, which increases performance. Remember that SELinux policy rules have no effect if DAC rules deny access first. + + +== SELinux states and modes + +SELinux can run in one of three modes: disabled, permissive, or enforcing. + +Disabled mode is strongly discouraged; not only does the system avoid enforcing the SELinux policy, it also avoids labeling any persistent objects such as files, making it difficult to enable SELinux in the future. + +In permissive mode, the system acts as if SELinux is enforcing the loaded security policy, including labeling objects and emitting access denial entries in the logs, but it does not actually deny any operations. While not recommended for production systems, permissive mode can be helpful for SELinux policy development. + +Enforcing mode is the default, and recommended, mode of operation; in enforcing mode SELinux operates normally, enforcing the loaded security policy on the entire system. + +Use the [command]`setenforce` utility to change between enforcing and permissive mode. Changes made with [command]`setenforce` do not persist across reboots. To change to enforcing mode, enter the [command]`setenforce 1` command as the Linux root user. To change to permissive mode, enter the [command]`setenforce 0` command. Use the [command]`getenforce` utility to view the current SELinux mode: + +---- +[~]# getenforce +Enforcing +---- + +---- +[~]# setenforce 0 +[~]# getenforce +Permissive +---- + +---- +[~]# setenforce 1 +[~]# getenforce +Enforcing +---- + +In Fedora, you can set individual domains to permissive mode while the system runs in enforcing mode. For example, to make the `httpd_t` domain permissive: + +---- +[~]# semanage permissive -a httpd_t +---- + + + + + diff --git a/modules/ROOT/pages/selinux-troubleshooting.adoc b/modules/ROOT/pages/selinux-troubleshooting.adoc new file mode 100644 index 0000000..f14bc42 --- /dev/null +++ b/modules/ROOT/pages/selinux-troubleshooting.adoc @@ -0,0 +1,313 @@ += Troubleshooting Problems Related to SELinux +Mat McCabe; Joe Walker; Peter Boy (pboy) +:revnumber: F36 and newer +:revdate: 2023-06-18 +:category: SELinux +:tags: How-to Security SELinux +:page-aliases: troubleshooting_selinux.adoc +//:imagesdir: ./images + +If you plan to enable SELinux on systems where it has been previously disabled or if you run a service in a non-standard configuration, you might need to troubleshoot situations potentially blocked by SELinux. Note that in most cases, SELinux denials are signs of misconfiguration. + +== Identifying SELinux denials + +Follow only the necessary steps from this procedure; in most cases, you need to perform just step 1. + +*Procedure* + +. When your scenario is blocked by SELinux, the [command]`/var/log/audit/audit.log` file is the first place to check for more information about a denial. To query Audit logs, use the `ausearch` tool. Because the SELinux decisions, such as allowing or disallowing access, are cached and this cache is known as the Access Vector Cache (AVC), use the `AVC` and `USER_AVC` values for the message type parameter, for example: ++ +---- +# ausearch -m AVC,USER_AVC,SELINUX_ERR,USER_SELINUX_ERR -ts recent +---- ++ +If there are no matches, check if the Audit daemon is running. If it does not, repeat the denied scenario after you start auditd and check the Audit log again. + +. In case auditd is running, but there are no matches in the output of ausearch, check messages provided by the systemd Journal: ++ +---- +# journalctl -t setroubleshoot +---- + +. If SELinux is active and the Audit daemon is not running on your system, then search for certain SELinux messages in the output of the dmesg command: ++ +---- +# dmesg | grep -i -e type=1300 -e type=1400 +---- + +. Even after the previous three checks, it is still possible that you have not found anything. In this case, AVC denials can be silenced because of `dontaudit` rules. ++ +To temporarily disable `dontaudit` rules, allowing all denials to be logged: ++ +---- +# semodule -DB +---- ++ +After re-running your denied scenario and finding denial messages using the previous steps, the following command enables `dontaudit` rules in the policy again: ++ +---- +# semodule -B +---- + +. If you apply all four previous steps, and the problem still remains unidentified, consider if SELinux really blocks your scenario: +* Switch to permissive mode: ++ +---- +# setenforce 0 +$ getenforce +Permissive +---- +* Repeat your scenario. + +If the problem still occurs, something different than SELinux is blocking your scenario. + +== Analyzing SELinux denial messages + +After identifying that SELinux is blocking your scenario, you might need to analyze the root cause before you choose a fix. + +*Prerequisites* + +** The `policycoreutils-python-utils` and `setroubleshoot-server` packages are installed on your system. + +*Procedure* + +. List more details about a logged denial using the `sealert` command, for example: ++ +---- +$ sealert -l "*" +SELinux is preventing /usr/bin/passwd from write access on the file +/root/test. + +***** Plugin leaks (86.2 confidence) suggests ***************************** + +If you want to ignore passwd trying to write access the test file, +because you believe it should not need this access. +Then you should report this as a bug. +You can generate a local policy module to dontaudit this access. +Do +# ausearch -x /usr/bin/passwd --raw | audit2allow -D -M my-passwd +# semodule -X 300 -i my-passwd.pp + +***** Plugin catchall (14.7 confidence) suggests ************************** + +... + +Raw Audit Messages +type=AVC msg=audit(1553609555.619:127): avc: denied { write } for +pid=4097 comm="passwd" path="/root/test" dev="dm-0" ino=17142697 +scontext=unconfined_u:unconfined_r:passwd_t:s0-s0:c0.c1023 +tcontext=unconfined_u:object_r:admin_home_t:s0 tclass=file permissive=0 + +.. + +Hash: passwd,passwd_t,admin_home_t,file,write +---- + +. If the output obtained in the previous step does not contain clear suggestions: + +* Enable full-path auditing to see full paths to accessed objects and to make additional Linux Audit event fields visible: ++ +---- +# auditctl -w /etc/shadow -p w -k shadow-write +---- + +* Clear the `setroubleshoot` cache: ++ +---- +# rm -f /var/lib/setroubleshoot/setroubleshoot.xml +---- + +* Reproduce the problem. +* Repeat step 1. ++ +After you finish the process, disable full-path auditing: ++ +---- +# auditctl -W /etc/shadow -p w -k shadow-write +---- + +. If `sealert` returns only `catchall` suggestions or suggests adding a new rule using the `audit2allow` tool, match your problem with examples listed and explained in SELinux denials in the Audit log. + +*Additional resources* + +* `sealert(8)` man page + +== Fixing analyzed SELinux denials + +In most cases, suggestions provided by the `sealert` tool give you the right guidance about how to fix problems related to the SELinux policy. See Analyzing SELinux denial messages for information how to use `sealert` to analyze SELinux denials. + +Be careful when the tool suggests using the `audit2allow` tool for configuration changes. You should not use `audit2allow` to generate a local policy module as your first option when you see an SELinux denial. Troubleshooting should start with a check if there is a labeling problem. The second most often case is that you have changed a process configuration, and you forgot to tell SELinux about it. + +**Labeling problems** + +A common cause of labeling problems is when a non-standard directory is used for a service. For example, instead of using `/var/www/html/` for a website, an administrator might want to use `/srv/myweb/`. On Red Hat Enterprise Linux, the `/srv` directory is labeled with the `var_t` type. Files and directories created in /srv inherit this type. Also, newly-created objects in top-level directories, such as `/myserver`, can be labeled with the `default_t` type. SELinux prevents the Apache HTTP Server (`httpd`) from accessing both of these types. To allow access, SELinux must know that the files in `/srv/myweb/` are to be accessible by `httpd`: + +---- +# semanage fcontext -a -t httpd_sys_content_t "/srv/myweb(/.*)?" +---- + +This `semanage` command adds the context for the `/srv/myweb/` directory and all files and directories under it to the SELinux file-context configuration. The `semanage` utility does not change the context. As root, use the `restorecon` utility to apply the changes: + +---- +# restorecon -R -v /srv/myweb +---- + +**Incorrect Context** +The `matchpathcon` utility checks the context of a file path and compares it to the default label for that path. The following example demonstrates the use of `matchpathcon` on a directory that contains incorrectly labeled files: + +---- +$ matchpathcon -V /var/www/html/* +/var/www/html/index.html has context unconfined_u:object_r:user_home_t:s0, should be system_u:object_r:httpd_sys_content_t:s0 +/var/www/html/page1.html has context unconfined_u:object_r:user_home_t:s0, should be system_u:object_r:httpd_sys_content_t:s0 +---- + +In this example, the `index.html` and `page1.html` files are labeled with the `user_home_t` type. This type is used for files in user home directories. Using the `mv` command to move files from your home directory may result in files being labeled with the `user_home_t` type. This type should not exist outside of home directories. Use the `restorecon` utility to restore such files to their correct type: + +---- +# restorecon -v /var/www/html/index.html +restorecon reset /var/www/html/index.html context unconfined_u:object_r:user_home_t:s0->system_u:object_r:httpd_sys_content_t:s0 +---- + +To restore the context for all files under a directory, use the `-R` option: + +---- +# restorecon -R -v /var/www/html/ +restorecon reset /var/www/html/page1.html context unconfined_u:object_r:samba_share_t:s0->system_u:object_r:httpd_sys_content_t:s0 +restorecon reset /var/www/html/index.html context unconfined_u:object_r:samba_share_t:s0->system_u:object_r:httpd_sys_content_t:s0 +---- + +**Confined applications configured in non-standard ways** + +Services can be run in a variety of ways. To account for that, you need to specify how you run your services. You can achieve this through SELinux booleans that allow parts of SELinux policy to be changed at runtime. This enables changes, such as allowing services access to NFS volumes, without reloading or recompiling SELinux policy. Also, running services on non-default port numbers requires policy configuration to be updated using the `semanage` command. + +For example, to allow the Apache HTTP Server to communicate with MariaDB, enable the `httpd_can_network_connect_db` boolean: + +---- +# setsebool -P httpd_can_network_connect_db on +---- + +Note that the `-P` option makes the setting persistent across reboots of the system. + +If access is denied for a particular service, use the `getsebool` and `grep` utilities to see if any booleans are available to allow access. For example, use the `getsebool -a | grep ftp` command to search for FTP related booleans: + +---- +$ getsebool -a | grep ftp +ftpd_anon_write --> off +ftpd_full_access --> off +ftpd_use_cifs --> off +ftpd_use_nfs --> off + +ftpd_connect_db --> off +httpd_enable_ftp_server --> off +tftp_anon_write --> off +---- + +To get a list of booleans and to find out if they are enabled or disabled, use the `getsebool -a` command. To get a list of booleans including their meaning, and to find out if they are enabled or disabled, install the `selinux-policy-devel` package and use the `semanage boolean -l` command as root. + +**Port numbers* + +Depending on policy configuration, services can only be allowed to run on certain port numbers. Attempting to change the port a service runs on without changing policy may result in the service failing to start. For example, run the `semanage port -l | grep http` command as root to list `http` related ports: + +---- +# semanage port -l | grep http +http_cache_port_t tcp 3128, 8080, 8118 +http_cache_port_t udp 3130 +http_port_t tcp 80, 443, 488, 8008, 8009, 8443 +pegasus_http_port_t tcp 5988 +pegasus_https_port_t tcp 5989 +---- + +The `http_port_t` port type defines the ports Apache HTTP Server can listen on, which in this case, are TCP ports 80, 443, 488, 8008, 8009, and 8443. If an administrator configures `httpd.conf` so that httpd listens on port 9876 (`Listen 9876`), but policy is not updated to reflect this, the following command fails: + +---- +# systemctl start httpd.service +Job for httpd.service failed. See 'systemctl status httpd.service' and 'journalctl -xn' for details. + +# systemctl status httpd.service +httpd.service - The Apache HTTP Server + Loaded: loaded (/usr/lib/systemd/system/httpd.service; disabled) + Active: failed (Result: exit-code) since Thu 2013-08-15 09:57:05 CEST; 59s ago + Process: 16874 ExecStop=/usr/sbin/httpd $OPTIONS -k graceful-stop (code=exited, status=0/SUCCESS) + Process: 16870 ExecStart=/usr/sbin/httpd $OPTIONS -DFOREGROUND (code=exited, status=1/FAILURE) +---- + +An SELinux denial message similar to the following is logged to `/var/log/audit/audit.log`: + +---- +type=AVC msg=audit(1225948455.061:294): avc: denied { name_bind } for pid=4997 comm="httpd" src=9876 scontext=unconfined_u:system_r:httpd_t:s0 tcontext=system_u:object_r:port_t:s0 tclass=tcp_socket +---- + +To allow `httpd` to listen on a port that is not listed for the `http_port_t` port type, use the `semanage port` command to assign a different label to the port: + +---- +# semanage port -a -t http_port_t -p tcp 9876 +---- + +The `-a `option adds a new record; the `-t` option defines a type; and the -p option defines a protocol. The last argument is the port number to add. + +**Corner cases, evolving or broken applications, and compromised systems** + +Applications may contain bugs, causing SELinux to deny access. Also, SELinux rules are evolving – SELinux may not have seen an application running in a certain way, possibly causing it to deny access, even though the application is working as expected. For example, if a new version of PostgreSQL is released, it may perform actions the current policy does not account for, causing access to be denied, even though access should be allowed. + +For these situations, after access is denied, use the `audit2allow` utility to create a custom policy module to allow access. You can report missing rules in the SELinux policy in Red Hat Bugzilla. For `Red Hat Enterprise Linux 8`, create bugs against the Red Hat Enterprise Linux 8 product, and select the `selinux-policy` component. Include the output of the `audit2allow -w -a` and `audit2allow -a` commands in such bug reports. + +If an application asks for major security privileges, it could be a signal that the application is compromised. Use intrusion detection tools to inspect such suspicious behavior. + +The Solution Engine on the Red Hat Customer Portal can also provide guidance in the form of an article containing a possible solution for the same or very similar problem you have. Select the relevant product and version and use SELinux-related keywords, such as selinux or avc, together with the name of your blocked service or application, for example: `selinux samba`. + +== SELinux denials in the audit log + +The Linux Audit system stores log entries in the `/var/log/audit/audit.log` file by default. + +To list only SELinux-related records, use the `ausearch` command with the message type parameter set to `AVC` and `AVC_USER` at a minimum, for example: + +---- +# ausearch -m AVC,USER_AVC,SELINUX_ERR,USER_SELINUX_ERR +---- + +An SELinux denial entry in the Audit log file can look as follows: + +---- +type=AVC msg=audit(1395177286.929:1638): avc: denied { read } for pid=6591 comm="httpd" name="webpages" dev="0:37" ino=2112 scontext=system_u:system_r:httpd_t:s0 tcontext=system_u:object_r:nfs_t:s0 tclass=dir +---- + +The most important parts of this entry are: + +* `avc: denied` - the action performed by SELinux and recorded in Access Vector Cache (AVC) +* `{ read }` - the denied action +* `pid=6591` - the process identifier of the subject that tried to perform the denied action +* `comm="httpd"` - the name of the command that was used to invoke the analyzed process +* `httpd_t` - the SELinux type of the process +* `nfs_t` - the SELinux type of the object affected by the process action +* `tclass=dir` - the target object class + +The previous log entry can be translated to: + +__SELinux__ denied the `__httpd__` process with PID 6591 and the `__httpd_t__` type to read from a directory with the `__nfs_t__` type. + +The following SELinux denial message occurs when the Apache HTTP Server attempts to access a directory labeled with a type for the Samba suite: + +---- +type=AVC msg=audit(1226874073.147:96): avc: denied { getattr } for pid=2465 comm="httpd" path="/var/www/html/file1" dev=dm-0 ino=284133 scontext=unconfined_u:system_r:httpd_t:s0 tcontext=unconfined_u:object_r:samba_share_t:s0 tclass=file +---- + +* `{ getattr }` - the `getattr` entry indicates the source process was trying to read the target file’s status information. This occurs before reading files. SELinux denies this action because the process accesses the file and it does not have an appropriate label. Commonly seen permissions include `getattr`, `read`, and `write`. +* `path="/var/www/html/file1"` - the path to the object (target) the process attempted to access. +* `scontext="unconfined_u:system_r:httpd_t:s0"` - the SELinux context of the process (source) that attempted the denied action. In this case, it is the SELinux context of the Apache HTTP Server, which is running with the `httpd_t` type. +* `tcontext="unconfined_u:object_r:samba_share_t:s0"` - the SELinux context of the object (target) the process attempted to access. In this case, it is the SELinux context of `file1`. + +This SELinux denial can be translated to: + +SELinux denied the `__httpd__` process with PID 2465 to access the `__/var/www/html/file1__` file with the `__samba_share_t__` type, which is not accessible to processes running in the httpd_t domain unless configured otherwise. + +**Additional resources** + +* `auditd(8)` and `ausearch(8)` man pages + +== Additional resources + +* link:https://access.redhat.com/articles/2191331[Basic SELinux Troubleshooting in CLI] +* RHEL 9: link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/using_selinux/index[Using SELinux] +* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/selinux_users_and_administrators_guide/index[RHEL 7, SELinux User's and Administrator's Guide] +* link:https://fedorapeople.org/~dwalsh/SELinux/Presentations/selinux_four_things.pdf[Four Key Causes of SELinux Errors] +* link:https://wiki.centos.org/HowTos/SELinux[CentOS Wiki How Tos: SELinux] \ No newline at end of file diff --git a/modules/ROOT/pages/troubleshooting_selinux.adoc b/modules/ROOT/pages/troubleshooting_selinux.adoc deleted file mode 100644 index af39770..0000000 --- a/modules/ROOT/pages/troubleshooting_selinux.adoc +++ /dev/null @@ -1,306 +0,0 @@ -= Troubleshooting problems related to SELinux -:toc: - -If you plan to enable SELinux on systems where it has been previously disabled or if you run a service in a non-standard configuration, you might need to troubleshoot situations potentially blocked by SELinux. Note that in most cases, SELinux denials are signs of misconfiguration. - -== Identifying SELinux denials - -Follow only the necessary steps from this procedure; in most cases, you need to perform just step 1. - -*Procedure* - -. When your scenario is blocked by SELinux, the [command]`/var/log/audit/audit.log` file is the first place to check for more information about a denial. To query Audit logs, use the `ausearch` tool. Because the SELinux decisions, such as allowing or disallowing access, are cached and this cache is known as the Access Vector Cache (AVC), use the `AVC` and `USER_AVC` values for the message type parameter, for example: -+ ----- -# ausearch -m AVC,USER_AVC,SELINUX_ERR,USER_SELINUX_ERR -ts recent ----- -+ -If there are no matches, check if the Audit daemon is running. If it does not, repeat the denied scenario after you start auditd and check the Audit log again. - -. In case auditd is running, but there are no matches in the output of ausearch, check messages provided by the systemd Journal: -+ ----- -# journalctl -t setroubleshoot ----- - -. If SELinux is active and the Audit daemon is not running on your system, then search for certain SELinux messages in the output of the dmesg command: -+ ----- -# dmesg | grep -i -e type=1300 -e type=1400 ----- - -. Even after the previous three checks, it is still possible that you have not found anything. In this case, AVC denials can be silenced because of `dontaudit` rules. -+ -To temporarily disable `dontaudit` rules, allowing all denials to be logged: -+ ----- -# semodule -DB ----- -+ -After re-running your denied scenario and finding denial messages using the previous steps, the following command enables `dontaudit` rules in the policy again: -+ ----- -# semodule -B ----- - -. If you apply all four previous steps, and the problem still remains unidentified, consider if SELinux really blocks your scenario: -* Switch to permissive mode: -+ ----- -# setenforce 0 -$ getenforce -Permissive ----- -* Repeat your scenario. - -If the problem still occurs, something different than SELinux is blocking your scenario. - -== Analyzing SELinux denial messages - -After identifying that SELinux is blocking your scenario, you might need to analyze the root cause before you choose a fix. - -*Prerequisites* - -** The `policycoreutils-python-utils` and `setroubleshoot-server` packages are installed on your system. - -*Procedure* - -. List more details about a logged denial using the `sealert` command, for example: -+ ----- -$ sealert -l "*" -SELinux is preventing /usr/bin/passwd from write access on the file -/root/test. - -***** Plugin leaks (86.2 confidence) suggests ***************************** - -If you want to ignore passwd trying to write access the test file, -because you believe it should not need this access. -Then you should report this as a bug. -You can generate a local policy module to dontaudit this access. -Do -# ausearch -x /usr/bin/passwd --raw | audit2allow -D -M my-passwd -# semodule -X 300 -i my-passwd.pp - -***** Plugin catchall (14.7 confidence) suggests ************************** - -... - -Raw Audit Messages -type=AVC msg=audit(1553609555.619:127): avc: denied { write } for -pid=4097 comm="passwd" path="/root/test" dev="dm-0" ino=17142697 -scontext=unconfined_u:unconfined_r:passwd_t:s0-s0:c0.c1023 -tcontext=unconfined_u:object_r:admin_home_t:s0 tclass=file permissive=0 - -.. - -Hash: passwd,passwd_t,admin_home_t,file,write ----- - -. If the output obtained in the previous step does not contain clear suggestions: - -* Enable full-path auditing to see full paths to accessed objects and to make additional Linux Audit event fields visible: -+ ----- -# auditctl -w /etc/shadow -p w -k shadow-write ----- - -* Clear the `setroubleshoot` cache: -+ ----- -# rm -f /var/lib/setroubleshoot/setroubleshoot.xml ----- - -* Reproduce the problem. -* Repeat step 1. -+ -After you finish the process, disable full-path auditing: -+ ----- -# auditctl -W /etc/shadow -p w -k shadow-write ----- - -. If `sealert` returns only `catchall` suggestions or suggests adding a new rule using the `audit2allow` tool, match your problem with examples listed and explained in SELinux denials in the Audit log. - -*Additional resources* - -* `sealert(8)` man page - -== Fixing analyzed SELinux denials - -In most cases, suggestions provided by the `sealert` tool give you the right guidance about how to fix problems related to the SELinux policy. See Analyzing SELinux denial messages for information how to use `sealert` to analyze SELinux denials. - -Be careful when the tool suggests using the `audit2allow` tool for configuration changes. You should not use `audit2allow` to generate a local policy module as your first option when you see an SELinux denial. Troubleshooting should start with a check if there is a labeling problem. The second most often case is that you have changed a process configuration, and you forgot to tell SELinux about it. - -**Labeling problems** - -A common cause of labeling problems is when a non-standard directory is used for a service. For example, instead of using `/var/www/html/` for a website, an administrator might want to use `/srv/myweb/`. On Red Hat Enterprise Linux, the `/srv` directory is labeled with the `var_t` type. Files and directories created in /srv inherit this type. Also, newly-created objects in top-level directories, such as `/myserver`, can be labeled with the `default_t` type. SELinux prevents the Apache HTTP Server (`httpd`) from accessing both of these types. To allow access, SELinux must know that the files in `/srv/myweb/` are to be accessible by `httpd`: - ----- -# semanage fcontext -a -t httpd_sys_content_t "/srv/myweb(/.*)?" ----- - -This `semanage` command adds the context for the `/srv/myweb/` directory and all files and directories under it to the SELinux file-context configuration. The `semanage` utility does not change the context. As root, use the `restorecon` utility to apply the changes: - ----- -# restorecon -R -v /srv/myweb ----- - -**Incorrect Context** -The `matchpathcon` utility checks the context of a file path and compares it to the default label for that path. The following example demonstrates the use of `matchpathcon` on a directory that contains incorrectly labeled files: - ----- -$ matchpathcon -V /var/www/html/* -/var/www/html/index.html has context unconfined_u:object_r:user_home_t:s0, should be system_u:object_r:httpd_sys_content_t:s0 -/var/www/html/page1.html has context unconfined_u:object_r:user_home_t:s0, should be system_u:object_r:httpd_sys_content_t:s0 ----- - -In this example, the `index.html` and `page1.html` files are labeled with the `user_home_t` type. This type is used for files in user home directories. Using the `mv` command to move files from your home directory may result in files being labeled with the `user_home_t` type. This type should not exist outside of home directories. Use the `restorecon` utility to restore such files to their correct type: - ----- -# restorecon -v /var/www/html/index.html -restorecon reset /var/www/html/index.html context unconfined_u:object_r:user_home_t:s0->system_u:object_r:httpd_sys_content_t:s0 ----- - -To restore the context for all files under a directory, use the `-R` option: - ----- -# restorecon -R -v /var/www/html/ -restorecon reset /var/www/html/page1.html context unconfined_u:object_r:samba_share_t:s0->system_u:object_r:httpd_sys_content_t:s0 -restorecon reset /var/www/html/index.html context unconfined_u:object_r:samba_share_t:s0->system_u:object_r:httpd_sys_content_t:s0 ----- - -**Confined applications configured in non-standard ways** - -Services can be run in a variety of ways. To account for that, you need to specify how you run your services. You can achieve this through SELinux booleans that allow parts of SELinux policy to be changed at runtime. This enables changes, such as allowing services access to NFS volumes, without reloading or recompiling SELinux policy. Also, running services on non-default port numbers requires policy configuration to be updated using the `semanage` command. - -For example, to allow the Apache HTTP Server to communicate with MariaDB, enable the `httpd_can_network_connect_db` boolean: - ----- -# setsebool -P httpd_can_network_connect_db on ----- - -Note that the `-P` option makes the setting persistent across reboots of the system. - -If access is denied for a particular service, use the `getsebool` and `grep` utilities to see if any booleans are available to allow access. For example, use the `getsebool -a | grep ftp` command to search for FTP related booleans: - ----- -$ getsebool -a | grep ftp -ftpd_anon_write --> off -ftpd_full_access --> off -ftpd_use_cifs --> off -ftpd_use_nfs --> off - -ftpd_connect_db --> off -httpd_enable_ftp_server --> off -tftp_anon_write --> off ----- - -To get a list of booleans and to find out if they are enabled or disabled, use the `getsebool -a` command. To get a list of booleans including their meaning, and to find out if they are enabled or disabled, install the `selinux-policy-devel` package and use the `semanage boolean -l` command as root. - -**Port numbers* - -Depending on policy configuration, services can only be allowed to run on certain port numbers. Attempting to change the port a service runs on without changing policy may result in the service failing to start. For example, run the `semanage port -l | grep http` command as root to list `http` related ports: - ----- -# semanage port -l | grep http -http_cache_port_t tcp 3128, 8080, 8118 -http_cache_port_t udp 3130 -http_port_t tcp 80, 443, 488, 8008, 8009, 8443 -pegasus_http_port_t tcp 5988 -pegasus_https_port_t tcp 5989 ----- - -The `http_port_t` port type defines the ports Apache HTTP Server can listen on, which in this case, are TCP ports 80, 443, 488, 8008, 8009, and 8443. If an administrator configures `httpd.conf` so that httpd listens on port 9876 (`Listen 9876`), but policy is not updated to reflect this, the following command fails: - ----- -# systemctl start httpd.service -Job for httpd.service failed. See 'systemctl status httpd.service' and 'journalctl -xn' for details. - -# systemctl status httpd.service -httpd.service - The Apache HTTP Server - Loaded: loaded (/usr/lib/systemd/system/httpd.service; disabled) - Active: failed (Result: exit-code) since Thu 2013-08-15 09:57:05 CEST; 59s ago - Process: 16874 ExecStop=/usr/sbin/httpd $OPTIONS -k graceful-stop (code=exited, status=0/SUCCESS) - Process: 16870 ExecStart=/usr/sbin/httpd $OPTIONS -DFOREGROUND (code=exited, status=1/FAILURE) ----- - -An SELinux denial message similar to the following is logged to `/var/log/audit/audit.log`: - ----- -type=AVC msg=audit(1225948455.061:294): avc: denied { name_bind } for pid=4997 comm="httpd" src=9876 scontext=unconfined_u:system_r:httpd_t:s0 tcontext=system_u:object_r:port_t:s0 tclass=tcp_socket ----- - -To allow `httpd` to listen on a port that is not listed for the `http_port_t` port type, use the `semanage port` command to assign a different label to the port: - ----- -# semanage port -a -t http_port_t -p tcp 9876 ----- - -The `-a `option adds a new record; the `-t` option defines a type; and the -p option defines a protocol. The last argument is the port number to add. - -**Corner cases, evolving or broken applications, and compromised systems** - -Applications may contain bugs, causing SELinux to deny access. Also, SELinux rules are evolving – SELinux may not have seen an application running in a certain way, possibly causing it to deny access, even though the application is working as expected. For example, if a new version of PostgreSQL is released, it may perform actions the current policy does not account for, causing access to be denied, even though access should be allowed. - -For these situations, after access is denied, use the `audit2allow` utility to create a custom policy module to allow access. You can report missing rules in the SELinux policy in Red Hat Bugzilla. For `Red Hat Enterprise Linux 8`, create bugs against the Red Hat Enterprise Linux 8 product, and select the `selinux-policy` component. Include the output of the `audit2allow -w -a` and `audit2allow -a` commands in such bug reports. - -If an application asks for major security privileges, it could be a signal that the application is compromised. Use intrusion detection tools to inspect such suspicious behavior. - -The Solution Engine on the Red Hat Customer Portal can also provide guidance in the form of an article containing a possible solution for the same or very similar problem you have. Select the relevant product and version and use SELinux-related keywords, such as selinux or avc, together with the name of your blocked service or application, for example: `selinux samba`. - -== SELinux denials in the audit log - -The Linux Audit system stores log entries in the `/var/log/audit/audit.log` file by default. - -To list only SELinux-related records, use the `ausearch` command with the message type parameter set to `AVC` and `AVC_USER` at a minimum, for example: - ----- -# ausearch -m AVC,USER_AVC,SELINUX_ERR,USER_SELINUX_ERR ----- - -An SELinux denial entry in the Audit log file can look as follows: - ----- -type=AVC msg=audit(1395177286.929:1638): avc: denied { read } for pid=6591 comm="httpd" name="webpages" dev="0:37" ino=2112 scontext=system_u:system_r:httpd_t:s0 tcontext=system_u:object_r:nfs_t:s0 tclass=dir ----- - -The most important parts of this entry are: - -* `avc: denied` - the action performed by SELinux and recorded in Access Vector Cache (AVC) -* `{ read }` - the denied action -* `pid=6591` - the process identifier of the subject that tried to perform the denied action -* `comm="httpd"` - the name of the command that was used to invoke the analyzed process -* `httpd_t` - the SELinux type of the process -* `nfs_t` - the SELinux type of the object affected by the process action -* `tclass=dir` - the target object class - -The previous log entry can be translated to: - -__SELinux__ denied the `__httpd__` process with PID 6591 and the `__httpd_t__` type to read from a directory with the `__nfs_t__` type. - -The following SELinux denial message occurs when the Apache HTTP Server attempts to access a directory labeled with a type for the Samba suite: - ----- -type=AVC msg=audit(1226874073.147:96): avc: denied { getattr } for pid=2465 comm="httpd" path="/var/www/html/file1" dev=dm-0 ino=284133 scontext=unconfined_u:system_r:httpd_t:s0 tcontext=unconfined_u:object_r:samba_share_t:s0 tclass=file ----- - -* `{ getattr }` - the `getattr` entry indicates the source process was trying to read the target file’s status information. This occurs before reading files. SELinux denies this action because the process accesses the file and it does not have an appropriate label. Commonly seen permissions include `getattr`, `read`, and `write`. -* `path="/var/www/html/file1"` - the path to the object (target) the process attempted to access. -* `scontext="unconfined_u:system_r:httpd_t:s0"` - the SELinux context of the process (source) that attempted the denied action. In this case, it is the SELinux context of the Apache HTTP Server, which is running with the `httpd_t` type. -* `tcontext="unconfined_u:object_r:samba_share_t:s0"` - the SELinux context of the object (target) the process attempted to access. In this case, it is the SELinux context of `file1`. - -This SELinux denial can be translated to: - -SELinux denied the `__httpd__` process with PID 2465 to access the `__/var/www/html/file1__` file with the `__samba_share_t__` type, which is not accessible to processes running in the httpd_t domain unless configured otherwise. - -**Additional resources** - -* `auditd(8)` and `ausearch(8)` man pages - -== Additional resources - -* link:https://access.redhat.com/articles/2191331[Basic SELinux Troubleshooting in CLI] -* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/selinux_users_and_administrators_guide/index[RHEL 7, SELinux User's and Administrator's Guide] -* link:https://fedorapeople.org/~dwalsh/SELinux/Presentations/selinux_four_things.pdf[Four Key Causes of SELinux Errors] -* link:https://wiki.centos.org/HowTos/SELinux[CentOS Wiki How Tos: SELinux] \ No newline at end of file