Performed review, updated links, etc.

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:selinux-getting-started.adoc[SELinux]
-** xref:changing-selinux-states-and-modes.adoc[Changing SELinux states and modes]
+** xref:selinux-changing-states-and-modes.adoc[Changing SELinux states and modes]
-** xref:troubleshooting_selinux.adoc[Troubleshooting SELinux]
+** 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]

modules/ROOT/pages/getting-started-with-selinux.adoc

@@ -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:]

modules/ROOT/pages/selinux-changing-states-and-modes.adoc

@@ -1,24 +1,19 @@
 = Changing SELinux States and Modes
- The Fedora Docs Team   
+ The Fedora Docs Team; Peter Boy (pboy)
 :revnumber: F36 and newer
 :revdate: 2023-08-09
-:category: Administration
+:category: SELinux
 :tags: How-to Security SELinux
+:page-aliases: changing-selinux-states-and-modes.adoc
 //: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
+// NOTE (TODO): several links (URLs) 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.
+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`.
 
@@ -47,11 +42,6 @@ To prevent incorrectly labeled and unlabeled files from causing problems, file s
 ====
 
 
-//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.
@@ -119,12 +109,6 @@ To run custom applications with SELinux in enforcing mode, choose one of the fol
 * 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. 
@@ -165,12 +149,6 @@ SELINUXTYPE=targeted
 ----
 
 
-
-/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.
@@ -247,11 +225,6 @@ If SELinux denies some actions, see the link:https://access.redhat.com/documenta
 ====
 
 
-//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.
@@ -319,10 +292,6 @@ 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:
@@ -351,5 +320,3 @@ For additional SELinux-related kernel boot parameters, such as [option]`checkreq
 ----
 [~]# dnf download --source kernel
 ----
-
-

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 <subject> do <action> to <object>?_, 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
+----
+
+
+
+
+

modules/ROOT/pages/selinux-troubleshooting.adoc

@@ -1,5 +1,11 @@
-= Troubleshooting problems related to SELinux
+= Troubleshooting Problems Related to SELinux
-:toc:
+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.
 
@@ -301,6 +307,7 @@ SELinux denied the `__httpd__` process with PID 2465 to access the `__/var/www/h
 == 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]