Quick Answer

Install troubleshooting tools: sudo dnf install setroubleshoot-server or sudo apt install setroubleshoot-server.
Search the main SELinux audit log: sudo grep "AVC" /var/log/audit/audit.log.
Use sealert to analyze a specific denial: sudo sealert -a /var/log/audit/audit.log.
Apply the suggested fix from sealert output, often a command to update the policy with semanage and restorecon.
Test if the application works after the fix. If not, consider temporary permissive mode for diagnosis: sudo setenforce 0.
Restore enforcing mode after fixing: sudo setenforce 1.

If this didn't work, follow the detailed checklist and symptom-based fixes below.

Before You Start

What You Need

Root or sudo access to the system.
Basic terminal/command-line familiarity.
The application error message or time it occurred.
SELinux must be in Enforcing mode (getenforce).
Audit daemon (auditd) should be running.

What Not to Do

Do not disable SELinux as a permanent first solution.
Avoid using chcon to change context unless you know it's correct; prefer restorecon.
Do not blindly add permissive domains; target the specific denial.
Avoid editing the raw binary policy files directly.

Fast Checklist

Confirm SELinux is the cause: Check if the app works in permissive mode (setenforce 0).
Check the main audit log: sudo tail -50 /var/log/audit/audit.log | grep AVC.
Check system logs: sudo journalctl -xe | grep -i sealert or sudo dmesg | grep -i selinux.
Install and run sealert for analysis.
Verify the file/directory security context: ls -laZ /path/to/file.
Restore default file contexts: sudo restorecon -Rv /path.
Check boolean values related to your service: getsebool -a | grep service_name.
Modify a boolean if needed: sudo setsebool -P bool_name on.
Add a custom policy module for a repeated, legitimate denial.
Relabel the entire filesystem if context corruption is widespread (touch /.autorelabel and reboot).
Ensure the audit daemon is running: sudo systemctl status auditd.
Review the denial type: Is it for a network port, file access, or process transition?
Check if the denial is for a non-standard directory; if so, assign the proper context.
Restart the application and audit service after making changes.
Always return SELinux to enforcing mode and test.

Mind Map / Flow Diagram

Application Fails
       │
       ▼
Is SELinux in Enforcing Mode? → No → Not an SELinux denial.
       │ (getenforce)
       Yes
       │
       ▼
Check Logs for "AVC" denial
       │
       ├─────────────────────────────────────────────────────────┐
       │                                                         ▼
       ▼                                        (Temporary Diagnostic Step)
Analyze with `sealert -a`                                 Set permissive mode
       │                                                   (`setenforce 0`)
       ▼                                                           │
┌──────────────┐                                           Does app work now?
│ Denial Type? │                                                  Yes
└──────────────┘                                                   │
       │                                                   SELinux is blocking it.
       ├─────────────────┬─────────────────┬───────────────────────┘
       │                 │                 │
       ▼                 ▼                 ▼
 File Context      Boolean        Port Access        Process Transition
   Issue          Issue              Issue                 Issue
       │                 │                 │                 │
       ▼                 ▼                 ▼                 ▼
`ls -laZ`          `getsebool`      `semanage port`    `ps -eZ`
`matchpathcon`                     `semanage permissive`
       │                 │                 │                 │
       ▼                 ▼                 ▼                 ▼
`restorecon`       `setsebool`     Add port label    Create custom policy
`chcon` (if known)                                (`audit2allow -M`)
       │                 │                 │                 │
       ▼                 ▼                 ▼                 ▼
            Test Application with `setenforce 1`
                          │
                          ▼
                 Success → Done. Update permanent fixes.
                 Failure → Re-analyze logs; consider policy module.

Step-by-Step Guide

Step 1: Confirm SELinux is Involved

What to do: Temporarily set SELinux to Permissive mode and test your application.

Why it helps: If the error disappears, SELinux is blocking something. If not, the problem lies elsewhere.

Expected outcome: You confirm SELinux is the root cause before spending time on logs.

Note: Always return to Enforcing mode (sudo setenforce 1) after testing. Use permissive mode only for diagnosis.

Step 2: Gather Denial Logs

What to do: Search for Access Vector Cache (AVC) denial messages in the audit log.

Why it helps: These logs contain specific details about what was denied (process, target, action).

Expected outcome: You find one or more recent denial messages with timestamps matching your application failure.

Step 3: Analyze with sealert

What to do: Install setroubleshoot-server and run sudo sealert -a /var/log/audit/audit.log.

Why it helps: This tool translates raw audit messages into human-readable explanations and often suggests specific commands to fix the issue.

Expected outcome: A clear summary of the denial with a suggested fix, such as "Run semanage fcontext ... and restorecon".

Step 4: Apply the Fix

What to do: Execute the recommended commands from sealert or from the specific fix categories below.

Why it helps: These commands adjust the SELinux policy or file contexts to allow the necessary operation.

Expected outcome: The policy is updated. The application's required access is now permitted.

Step 5: Test and Enforce

What to do: Restart your application and ensure SELinux is back in Enforcing mode.

Why it helps: Verifies the fix works under normal, secure conditions.

Expected outcome: The application runs successfully with getenforce showing "Enforcing". No new denials appear in logs.

Common Causes (Explain Like I’m Busy)

Incorrect file context: A file or directory is labeled with the wrong SELinux type. Symptom: "Permission denied" when accessing data in a non-standard location.
Restrictive boolean: A global SELinux switch (boolean) for a service (like HTTP, NFS, DB) is off. Symptom: Service starts but fails to perform a specific function (e.g., serving user directories).
Missing port label: A service tries to listen on a TCP/UDP port not defined in SELinux policy. Symptom: Service fails to bind to a port, even though the port is free.
Process transition denial: A process tries to execute a binary or transition to a domain not allowed. Symptom: Script or cron job fails silently or with cryptic errors.
Widespread mislabeling: Filesystem was not relabeled after a major OS upgrade or restore. Symptom: Multiple, seemingly unrelated services fail.
Custom application policy: A custom or third-party app has no SELinux policy. Symptom: App works in permissive mode but not enforcing.
Audit daemon stopped: Denials aren't logged properly, making diagnosis impossible. Symptom: No "AVC" messages in logs despite suspected denial.

Diagnostics

SELinux is a Linux-specific feature. Use these built-in tools.

Primary Log Location

The main audit log is your first stop. Commands to view relevant entries:

Recent AVC denials: sudo ausearch -m avc -ts recent
Tail the log for real-time monitoring: sudo tail -f /var/log/audit/audit.log | grep AVC
If /var/log/audit/audit.log is empty, check if auditd is running.

Context Inspection Tools

Check the security labels on files, processes, and ports.

File/Directory context: ls -Z /path/to/file
Process context: ps -eZ | grep process_name
Port labels: sudo semanage port -l
Boolean values: getsebool -a

Analysis Tools

Tools to interpret raw audit messages.

sealert (from setroubleshoot): Provides the clearest analysis and fixes.
audit2why: Translates a specific denial from the audit log into a human-readable reason.
audit2allow: Generates policy rules from denials. Use with caution.

Fixes by Symptom

Symptom: Web server can't access user content in `/home/user/www`.

Likely cause: Wrong file context on the directory.

Best first fix: sudo semanage fcontext -a -t httpd_sys_content_t "/home/user/www(/.*)?"
Then sudo restorecon -Rv /home/user/www.

Next fix: Check and set the httpd_enable_homedirs boolean: sudo setsebool -P httpd_enable_homedirs on.

Symptom: FTP server fails to upload files to a custom directory.

Likely cause: Directory lacks public_content_rw_t context.

Best first fix: sudo semanage fcontext -a -t public_content_rw_t "/custom/path(/.*)?"
sudo restorecon -Rv /custom/path.

Next fix: Ensure the ftp_home_dir or allow_ftpd_full_access boolean is on if needed.

Symptom: Database service (e.g., MySQL) can't start on a non-default port.

Likely cause: The port is not labeled for the database service.

Best first fix: Add the port label: sudo semanage port -a -t mysqld_port_t -p tcp 3307 (replace 3307 with your port).

Next fix: Check for other denials related to file access in /var/lib/mysql.

Symptom: Custom application fails only when SELinux is enforcing.

Likely cause: No SELinux policy for the application.

Best first fix: Generate a custom policy module from denial logs: sudo grep -i deny /var/log/audit/audit.log | audit2allow -M myapp
Then install it: sudo semodule -i myapp.pp.

Next fix: Manually review and refine the generated .te policy file for security before installing.

Symptom: Samba shares are inaccessible by clients.

Likely cause: Samba booleans are disabled or share context is wrong.

Best first fix: Set relevant booleans: sudo setsebool -P samba_export_all_rw on.

Next fix: Ensure share directories have the samba_share_t context using semanage fcontext and restorecon.

Symptom: Cron job doesn't execute a script as expected.

Likely cause: The cron service (crond_t) is denied transition to the script's domain.

Best first fix: Check the script's context and ensure it's executable. Try sudo restorecon -v /path/to/script.

Next fix: If the script needs a special policy, generate a module from the specific cron-related denial.

Advanced

Creating Custom Policy Modules with audit2allow

For persistent, legitimate denials, create a tailored policy module. Extract relevant AVC denials, generate a .te file, review it, compile, and load it. This is safer than disabling SELinux for a domain.

Understanding SELinux Modes: Enforcing, Permissive, Disabled

Enforcing denies and logs. Permissive only logs (for troubleshooting). Disabled turns it off entirely (requires reboot). Changing between disabled and enforcing requires a filesystem relabel on the next boot.

Managing File Contexts with semanage fcontext

The semanage fcontext command manages the persistent context mapping database. Changes made with chcon may be overwritten by a restorecon or system relabel unless the mapping is added here first.

Interpreting Raw AVC Audit Log Messages

A raw AVC message contains: scontext (source context/process), tcontext (target context/file/port), and tclass (target class). Understanding these helps manually craft policy rules.

Using semanage permissive to Add a Permissive Domain

Instead of making the entire system permissive, you can set a specific process type (domain) to permissive: sudo semanage permissive -a httpd_t. This allows that domain to run while keeping the rest of the system enforcing. Useful for debugging a single service.

Prevention & Best Practices

Always place application data in directories with the correct default SELinux context (e.g., /var/www/ for web, /var/ftp/ for FTP).
When creating custom directories for services, immediately assign the proper persistent file context using semanage fcontext and restorecon.
Before deploying a custom or third-party application, check if an SELinux policy package is available (e.g., .rpm or .deb).
Use booleans to toggle broad policy features instead of creating custom modules for common scenarios.
After major system upgrades, consider checking if a full filesystem relabel is recommended.
Monitor /var/log/audit/audit.log periodically for unexpected denials, even if services appear to work.
When generating custom policies with audit2allow, always review the generated .te file to ensure it's not granting excessive permissions.
Keep the setroubleshoot-server package installed for easier future diagnostics.
Document any custom SELinux policies or context changes made to the system.
Test policy changes in a staging environment before applying to production.
Understand that disabling SELinux is a security regression; treat it as a last resort.
Use sesearch and seinfo to explore the existing policy and understand allowed rules.

Frequently Asked Questions

What's the difference between chcon and restorecon?

chcon changes the context immediately but may not survive a relabel. restorecon resets the context based on the system's policy database, making it the preferred, persistent method.

How do I permanently disable SELinux?

Edit /etc/selinux/config and set SELINUX=disabled, then reboot. This is not recommended for security. Use permissive mode for troubleshooting instead.

My audit log is huge. How do I clear it?

Use sudo truncate -s 0 /var/log/audit/audit.log (if allowed by policy) or configure log rotation in /etc/audit/auditd.conf.

Why does my fix work but sealert still shows old denials?

sealert -a reads the entire log file. Analyze only new denials after your fix by using sudo ausearch -m avc -ts recent or clearing the log before testing.

What does "unconfined_t" mean in a log?

It means the process is running in an unconfined domain, largely unrestricted by SELinux. Denials often involve the target (tcontext), not the source, in this case.

How can I list all SELinux booleans relevant to Apache?

Use: getsebool -a | grep httpd. This shows all booleans with "httpd" in their name.

Is it safe to delete custom policy modules?

Yes, use sudo semodule -r module_name to remove a module. Ensure the underlying cause of the denial has been otherwise resolved first.

When should I stop and ask a professional?

If you are dealing with a critical production system, if denials are numerous and cryptic, or if you suspect policy corruption, seek help from a security professional or your distribution's support channels.

References / Sources

Red Hat Enterprise Linux SELinux Documentation
Fedora Project: SELinux User Guide
CentOS Wiki: SELinux Howto
Ubuntu Community Help Wiki: SELinux
Arch Linux Wiki: SELinux
National Security Agency (NSA) SELinux Design Documentation
SELinux man pages: man selinux, man auditd, man semanage
systemd and journalctl documentation for log integration

Menu

How to troubleshoot SELinux denials in logs

AI Assistant

Was this tool helpful?