Diagnosing SELinux errors and selectively permitting them: from permissive mode to policy modules

When a service reports „Permission denied“, SELinux error diagnosis is a central step: the system enforces Mandatory Access Control (MAC), which decides beyond classic Unix permissions. In this guide you will learn in practical terms how to diagnose SELinux errors, evaluate AVC denials, use permissive mode in a controlled way, correct labels, ports and booleans and — only if necessary — create small policy modules. Target audience: administrators, system engineers, operators and technical service providers. Focus: secure operational procedures, Docker/Podman pitfalls, verification sequences and fallback strategies.

Brief: What SELinux does and how denials appear

SELinux is a Mandatory Access Control (MAC). Unlike ordinary file permission management (Discretionary Access Control, DAC), SELinux decides based on security contexts (e.g. user:role:type:level) which domain (a process context, e.g. httpd_t or container_t) may perform which actions on an object (file, socket, port). A denied access is logged as an AVC Denial (Access Vector Cache) and is the primary source for diagnosis.

Systematic troubleshooting sequence: how to work purposefully

Work through a fixed sequence to avoid unnecessary changes and to reduce the blast radius. Order: Status → Reproduce → Collect logs → Context analysis → Remediation strategy (Label/Port/Boolean → permissive for collection → Policy module) → Test → Rollback.

Check status and secure logs

# Modus und Policy
sestatus
getenforce

# Audit-Log (RHEL/Fedora) ansehen
sudo tail -n 200 /var/log/audit/audit.log

# Kurz-Report über AVCs
sudo aureport --avc --summary

Before you make changes: copy relevant log sections into your incident ticket. That facilitates review, testing and rollback.

Reproduce the denial and narrow it down in time

# AVC-Einträge seit Reproduktionszeitpunkt
sudo ausearch -m AVC,USER_AVC -ts recent

# AVC-Einträge in Datei schreiben
sudo ausearch -m AVC -ts 2026-07-27 10:00:00 > /tmp/avc.log

Important: Execute the failing workflow within the most isolated test window possible so the collected AVCs remain comprehensible.

AVC log: example and field interpretation

# Beispiel eines AVC-Eintrags (gekürzt)
type=AVC msg=audit(1627392000.123:456): avc:  denied  { write } for  pid=2345 comm="httpd" name="uploads" dev="sda1" ino=12345 scontext=system_u:system_r:httpd_t:s0 tcontext=unconfined_u:object_r:usr_t:s0 tclass=file

Key fields: scontext (source context = process domain), tcontext (target context = file type), tclass (object class, e.g. file, tcp_socket) and the action (e.g. write). If tcontext does not match the expected type (e.g. usr_t instead of httpd_sys_rw_content_t), SELinux will raise an alert — even if Unix permissions are correct.

audit2why as the first interpretation

# Erklärung der Gründe
sudo ausearch -m AVC -ts recent | sudo audit2why

audit2why maps denials to policy rules and provides hints (e.g. which Boolean might help). Use its output as a guide, not as an automatic fix plan.

Correcting labels: chcon vs. semanage fcontext & RESTorecon

chcon changes an object’s context immediately, but it is not persistent: a relabel (during RESTore or a system-wide relabel) will overwrite it. semanage fcontext stores a permanent rule in the SELinux configuration database; RESTorecon applies that rule to files.

# Schnell: prüfen
ls -lZ /var/www/html/uploads

# Persistente Zuordnung erstellen
sudo semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/html/uploads(/.*)?"
sudo RESTorecon -Rv /var/www/html/uploads

# Nur simuliert anzeigen, was verändert würde
sudo RESTorecon -Rvn /var/www/html/uploads

Relabel during system migration or RESTore

After a RESTore from backups or a migration, SELinux contexts often need to be reset. For a full, planned relabel operation use:

# Vollständiges Relabel beim nächsten Boot (vorsichtig einsetzen)
sudo touch /.autorelabel
sudo reboot

Alternatively: targeted RESTorecon calls on the affected paths. For large file sets plan maintenance windows and check I/O load.

Ports, Booleans and network access

SELinux also governs port assignments and predefined behavioral options (Booleans). If a service runs on a non-standard port or requires network access, check ports and Booleans before creating a policy module.

# Port-Typen listen und Port hinzufuegen
sudo semanage port -l | grep http_port_t || true
sudo semanage port -a -t http_port_t -p tcp 8081

# Boolean anzeigen und permanent setzen
getsebool -a | grep '^httpd_'
sudo setsebool -P httpd_can_network_connect on

Booleans are policy-defined switches. Use -P to make the setting persistent (across reboots).

Docker & Podman: Volumes, :Z/:z and typical operational pitfalls

Container processes run in dedicated SELinux domains (e.g. container_t). For mounted host volumes the host path must be labeled appropriately, otherwise accesses remain blocked even if Unix permissions are correct. Engines provide convenient relabel flags.

:Z vs :z — practical meaning

• :Z creates a private label for this container (safer for individual containers).
• :z allows a shared label for multiple containers (suitable for shared data, but less RESTrictive).

# Docker: Hostpfad für Container relabeln
docker run --rm -v /srv/appdata:/var/lib/app:Z myimage

# Podman hat analoges Verhalten
podman run --rm -v /srv/appdata:/var/lib/app:Z myimage

Important: relabels change host labels. Inform backup jobs, monitoring agents and host processes, as they may have different expectations regarding SELinux contexts.

Containers and NFS

With NFS SELinux is particularly sensitive: NFS servers do not always pass SELinux contexts. In such cases check special Booleans, NFS server settings or alternative storage strategies. Plan container workloads with NFS access early, otherwise long-term policy exceptions may arise.

Policy‑Module: create, review and deploy in a controlled manner

Create modules only when labels, ports and Booleans do not solve the problem. Modules are long-lived and should, like any configuration change, be versioned, reviewed and tested.

Recommended procedure for modules

1. Temporarily set the domain to permissive (collection only).
2. Execute the relevant workflow and collect AVCs.
3. Use audit2allow, inspect the .te and RESTrict it manually.
4. Test the module in staging; semodule -i in the production rollout phase within a change window.
5. Test rollback (semodule -r) and create documentation.

# Beispiel: Modul erzeugen und installieren
sudo semanage permissive -a httpd_t
# Tests durchführen und AVCs sammeln
sudo ausearch -m AVC -ts recent > /tmp/avc.log
sudo semanage permissive -d httpd_t
sudo audit2allow -M local_app_fix -i /tmp/avc.log
# .te prüfen, dann installieren
cat local_app_fix.te
sudo semodule -i local_app_fix.pp

# Modul entfernen (Rollback)
sudo semodule -r local_app_fix

Review .te files carefully: audit2allow generates rules based on observed activity; these rules can be too broad and should be manually RESTricted, e.g. by operation (write vs append) or target objects.

Practical example: web server cannot write to upload directory

1. Check the error message and note the timestamp.
2. Collect AVCs: ausearch/audit log.
3. Inspect contexts: ls -lZ, ps -eZ.
4. Try RESTorecon first; if necessary set semanage fcontext.
5. If network access is required: check booleans/ports.
6. If nothing fits: set permissive briefly, collect data, build and test a module.

# Diagnose-Schritte
ls -lZ /var/www/html/uploads
sudo ausearch -m AVC -ts recent | sudo audit2why
sudo RESTorecon -Rv /var/www/html/uploads
# Falls persistent benoetigt
sudo semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/html/uploads(/.*)?"
sudo RESTorecon -Rv /var/www/html/uploads

Backup, RESTore and migration: preserve SELinux contexts

When copying or migrating data, SELinux contexts are extended attributes (xattrs). Use tools that preserve xattrs; otherwise denials are likely after RESTore.

# Rsync inkl. xattrs, ACLs und besonderen Flags
rsync -aHAX --numeric-ids --delete /srv/source/ /srv/dest/

# Nach RESTore gezielt relabeln
sudo RESTorecon -Rv /srv/dest

Plan migrations with a test run and relabel checks; for large datasets a staged approach with sampling can be appropriate.

Monitoring, alerting and automation

Regular AVC analysis helps detect regressions. Tools such as auditd/aureport, setroubleshoot (sealert) or centralized log pipelines (ELK, Splunk) are useful. Set thresholds for AVC rates in your monitoring and create tickets on sudden spikes.

# Schnelle Übersicht
sudo aureport --avc --summary

# sealert für verständliche Hinweise
sudo sealert -a /var/log/audit/audit.log | head -n 200

Document every change (semanage, setsebool, semodule) in your CMDB/change ticket including reasons, test VM and rollback plan.

Configuration management: example Ansible task

- name: Persistente SELinux-Fcontext für Uploads setzen
  become: true
  command: >
    semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/html/uploads(/.*)?"
  changed_when: false

- name: RESTorecon auf Uploads anwenden
  become: true
  command: RESTorecon -Rv /var/www/html/uploads

In automation playbooks, test idempotence and validate changes with dry runs (RESTorecon -vn) before rolling out to production.

Final checklist before production change

• Attach AVC log backup to the ticket.
• Check fix priority: Label → Port → Boolean → Module.
• Set permissive only briefly and document it.
• Commit module files (.te/.pp) to Git; use code review and test VMs.
• Ensure rollback is tested and recorded in the ticket.

Conclusion

SELinux provides strong additional security, but requires systematic work: log-based diagnostics, preferred correction via Label/Port/Boolean, targeted collection in permissive mode and only then lean policy modules. Especially for container workloads, plan SELinux compliance already in the architecture phase. Version, test and document every policy change so that operations, backup/RESTore and audits remain reliable.

FAQ

See the FAQ at the end of the article for quick answers to common questions.

Diagnosing SELinux errors: CI/CD, rollout and governance

Beyond individual fixes, it is worth integrating SELinux artifacts into your operations and deployment processes. That reduces long-term risk, ensures reproducibility and prevents broad, untidy policy changes in production.

Policy modules in CI: collection, review, build

Automate the generation and validation of policy proposals. Structure: tests in an isolated staging environment (ideally identical to production), temporarily allow permissive domains, collect AVCs, use audit2allow as a starting point, check the .te file into the repository and only build after manual RESTriction.

# CI-Schritte: Beispiel (vereinfachte Darstellung)
# 1) permissive für Domain setzen (nur Stage)
sudo semanage permissive -a myapp_t
# 2) Integrationstests laufen lassen, AVCs sammeln
sudo ausearch -m AVC -ts recent > avc-stage.log
# 3) audit2allow ausführen und .te erzeugen
sudo audit2allow -M myapp_fix -i avc-stage.log
# 4) statische Prüfung (Developer/Reviewer prüft myapp_fix.te)
# 5) Build & Paket
checkmodule -M -m -o myapp_fix.mod myapp_fix.te
semodule_package -o myapp_fix.pp -m myapp_fix.mod

Das erzeugte .te-File gehört ins Git, inklusive Review-Comments und Tests, bevor das .pp in Staging installiert wird.

Safe rollout: Canary, Monitoring, Revert

• Perform a canary deployment: install the module first on a small group of hosts.
• Track AVC rates and business metrics in parallel; set alerts for sudden increases.
• Test the revert path: semodule -r modulname must remove cleanly without side effects and RESTore functionality.

Versioning and naming convention

Name modules with service, ticket number and version (e.g. myapp_fix-T1234-v1). Store .te/.pp and audit logs in the change ticket/repo so audits and postmortems are traceable.

Check diversity: distributions, kernel, container engines

SELinux policy subtleties can vary between RHEL/CentOS, Fedora and Debian/Ubuntu (different policy packages and booleans). Test modules across the matrix that reflects your landscape: distro version × Kernel-Version × container engine (Docker/Podman) × storage type (local/NFS).

Operational risks and hard limits

Watch for privilege erosion: broad allow rules (e.g. allow container_t self:process) increase attack surface. Limit rules to specific object classes, operations and path patterns. Document exception rules with a risk assessment, time windows and ownership for later reviews.

Automated preflight checks

Before production installations, use automated preflight checks: semodule -l (before/after), test execs of critical use cases, and automatic diff analysis of the generated .te for allowed patterns. These checks can be easily integrated into CI pipelines and prevent unintentional policy inflation.

Such governance measures make SELinux changes transparent, reproducible and safer for operation and compliance — a clear advantage for operators of bespoke enterprise software and process-oriented software solutions.

For this topic, analyzing SELinux denials and audit.log is also important. The article places these aspects into context in a clear way and shows what matters in day-to-day operations.