SELinux — Making it a Little Easier for Web
A SELinux tutorial for your web site and web apps, the easy way — and why you shouldn’t disable SELinux.
If you’ve ever configured a server using a stock CentOS image, then you’ve likely run into SELinux. You might have run into this thing that seemed to block everything you were trying to do, thrown your hands up and decided to Google, “how to disable SELinux”. STOP. Don’t do that.
[You threw your hands up] and decided to Google, “how to disable SELinux”. STOP. Don’t do that.
What is SELinux, and why is it slowing me down?
The “SE” in SELinux stands for “Security-Enhanced” — and for good reason. I could probably write books about all the security aspects of a Linux system that can be managed by SELinux, but the important thing to know is that SELinux is like a watch-dog with nano-level focus on every part of your system in Linux. It prevents unauthorized changes to files and directories and also prevents various protocols like HTTP and SSH from being used by various services and applications unless you explicitly allow that action.
That said, it can seem like kind of a pain to get SELinux to play well with the things you’re trying to use in your CentOS system, and sometimes it seems like it’s just fighting you just to be a jerk.
…sometimes it seems like it’s just fighting you just to be a jerk.
The truth is, it’s just very, very good at doing what it was designed to do: watch every little file change and access attempt and making sure it’s legit. With a little coaxing we can make this work in our favor, and allow our app to run as expected, securely.
I assure you SELinux can be an easy-to-manage and vital part of security for your Linux system. It can be a strong force to contend with for hackers when it’s configured correctly.
It can be a strong force to contend with for hackers when it’s configured correctly.
In this tutorial, we will cover the basic SELinux configuration you will need for using HTTP/S applications like web sites and web apps, as well as how to address the nuances of SELinux when it doesn’t play well with your app.
We’ll also learn to use some powerful, but easy-to-use command line tools that will make managing your SELinux-hardened server a breeze. That’s right: I said SELinux and “a breeze” in the same sentence.
Ready to use SELinux the right way, easily? Read on.
Disclaimer: Use at your own risk.
I will do my best to cover the basics you will need to configure SELinux for web sites and web apps. You should know that completely disabling SELinux is inherently less secure.
Disabling SELinux is inherently less secure.
On the other hand, I can’t cover every use case and it’s possible that some points we will cover may or may not apply to your configuration — I can’t guarantee this will be the 100% most secure configuration of SELinux for your situation.
I can guarantee it will be a hell of a lot more secure than disabling SELinux entirely.
Last, SELinux configurations may take a few days of testing with your site or app to confirm that you’ve got all the custom rules set that are required for your use case. We’ll address this in more detail later on when we discuss the command line tools.
For now, just know that every good server admin monitors their work periodically to make sure it’s effective, and this is no different.
Before We Start (Prerequisites & Gotchas)
It’s suggested your CentOS system is up to date with the latest updates and kernel version before starting. yum update also installs the latest SELinux policies.
Many of these steps will require root or sudo access. You will need full administrative rights on the system you are modifying SELinux policy on. It is 100% safe to do this as root, in fact recommended as there can be conflicts when non-root users modify these kind of system-wide settings.
While SELinux can be installed on Ubuntu/Debian and other Linux distributions, this guide does not cover those configurations.
Install The Tools
Before we get started we’ll want to install a couple of tools that will make this whole SELinux business a lot smoother. We’re going to install tools specifically made for managing and troubleshooting SELinux.
We won’t do anything else with these until later, but let’s make sure they’re installed now.
$> yum install -y policycoreutils-python setroubleshootCheck SELinux Enforcement Status
Before we make any changes to SELinux, we want to be sure if it is currently enabled. We can do this a couple of different ways.
# Bash prompt
$> getenforce# The output here will be one of three values:
Enforcing
Permissive
Disabled
If the value returned is anything other than Disabled, we’re fine. If it’s Disabled, we will need to reset SELinux policies to their default state to ensure that when we enable it all policies other than the ones we allow are in force.
First, let’s review another option for verifying SELinux enforcement status.
$> cat /etc/selinux/config# 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 three two values:
# targeted - Targeted processes are protected,
# minimum - Modification of targeted policy. Only selected processes are protected.
# mls - Multi Level Security protection.
SELINUXTYPE=targeted
Your SELinux settings should reflect what is seen above — SELINUX=enforcing and SELINUXTYPE=targeted. If you see any other value do one of the following:
- If you see the value
permissivethen change it toenforcingusing Vi, Vim or nano. Using Linux text editors is outside the scope of this tutorial, but using Vi you can dovi /etc/selinux/config. Reboot after changing this for it to take effect. - If you see the value
disabledyou need to follow the steps in the next section, otherwise you can skip to “Reviewing Policy Options”.
Correcting SELinux Policies from a Disabled State
If SELinux has been disabled, it can cause a number of polices to be dropped, or invalidated. This means we can’t simply enable it again and expect it to work right. We need to reset policy values to default first.
First, modify the SELinux enforcement status in the config.
$> vi /etc/selinux/config# Change SELINUX=disabled to SELINUX=enforcing
# Save the file:wq# Verify your change
$> cat /etc/selinux/config
# 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
Then create a file in the server root directory called .autorelabel. Then reboot.
$> touch /.autorelabel
$> rebootThis action will return the SELinux policies to their default. After reboot we’re ready to continue configuring our policies.
Reviewing Policy Options
You can get a list of existing SELinux policy settings and also review this for options to resolve any conflicts you might have. This is a good way to plan the settings you may need to configure for a particular type of application.
As I said earlier, this tutorial will focus on the settings we need for web sites and web apps. This means we will be targeting policies related to HTTP, HTTPS, and file system access. However, these tools can be used to identify other built-in policies that may apply to many situations. I encourage you to experiment with them and identify how you might apply them when you run into other SELinux roadblocks.
Luckily for us, SELinux comes with many built-in HTTP-related polices. These can make it very easy to configure the rules needed for common web servers like Apache and Nginx. We’ll be using Nginx as an example for this tutorial. But first, let’s take a look at which built-in policies we may need to apply.
To see a list of all built-in policy booleans you can use getsebool -a — but wait! We don’t want all policies — just the HTTP-related ones.
$> getsebool -a | grep httpThis will return the list below. I’ve bolded the ones we are most likely to need. Note that if you’re using a php application you will need the CGI rule. Not everyone will need this, and it’s best to leave it disabled if you’re not using php.
httpd_anon_write --> off
httpd_builtin_scripting --> on
httpd_can_check_spam --> off
httpd_can_connect_ftp --> off
httpd_can_connect_ldap --> off
httpd_can_connect_mythtv --> off
httpd_can_connect_zabbix --> off
httpd_can_network_connect --> off
httpd_can_network_connect_cobbler --> off
httpd_can_network_connect_db --> off
httpd_can_network_memcache --> off
httpd_can_network_relay --> off
httpd_can_sendmail --> off
httpd_dbus_avahi --> off
httpd_dbus_sssd --> off
httpd_dontaudit_search_dirs --> off
httpd_enable_cgi --> off
httpd_enable_ftp_server --> off
httpd_enable_homedirs --> off
httpd_execmem --> off
httpd_graceful_shutdown --> on
httpd_manage_ipa --> off
httpd_mod_auth_ntlm_winbind --> off
httpd_mod_auth_pam --> off
httpd_read_user_content --> off
httpd_run_ipa --> off
httpd_run_preupgrade --> off
httpd_run_stickshift --> off
httpd_serve_cobbler_files --> off
httpd_setrlimit --> off
httpd_ssi_exec --> off
httpd_sys_script_anon_write --> off
httpd_tmp_exec --> off
httpd_tty_comm --> off
httpd_unified --> off
httpd_use_cifs --> off
httpd_use_fusefs --> off
httpd_use_gpg --> off
httpd_use_nfs --> off
httpd_use_openstack --> off
httpd_use_sasl --> off
httpd_verify_dns --> off
named_tcp_bind_http_port --> off
prosody_bind_http_port --> offEnabling Built-In Policies
In order to enable our HTTP policies we can use a simple command called setsebool as in “set SELinux boolean”. To enable our most common policies, run the following:
$> setsebool -P httpd_can_network_connect=1
setsebool -P httpd_can_network_connect_db=1
setsebool -P httpd_can_network_memcache=1
setsebool -P httpd_can_network_relay=1
setsebool -P httpd_can_sendmail=1
setsebool -P httpd_enable_cgi=1
setsebool -P httpd_enable_homedirs=1As we’ll see in the next step, this doesn’t quite do it for our web server. These policy settings are necessary, but incomplete for most use cases.
Install NGINX to For Testing
For testing for the purposes of this tutorial, I’m going to install Nginx, a very popular asynchronous web server. While my settings will be somewhat targeted to NGINX, they are by no means irrelevant to web servers like Apache — in fact, they may be nearly identical.
We’ll review how you can use the tools we installed earlier to isolate and correct SELinux policy configurations in a way that you can apply to any HTTP/HTTPS situation.
First, to install NGINX, add their repo to your repository files.
$> echo '[nginx]
name=nginx repo
baseurl=http://nginx.org/packages/centos/$releasever/$basearch/
gpgcheck=0
enabled=1' > /etc/yum.repos.d/nginx.repoNow, run yum update -y to have yum download the latest updates from the repo you just added. Then install, enable and start NGINX.
$> yum install -y nginx$> systemctl enable nginx
Created symlink from /etc/systemd/system/multi-user.target.wants/nginx.service to /usr/lib/systemd/system/nginx.service.$> systemctl start nginx
If we visit our server IP address in a browser, we’ll see the default nginx welcome page.
So everything is fine, right? Sure, unless we modify anything about where NGINX is serving files from. We’ll look at that in the next section.
Simulating Common SELinux Web Server Conflicts
I’ll now configure NGINX to demonstrate a common issue you may face with web servers and SELinux: the web server will be denied access to the web root.
The default location for NGINX web root is /usr/local/nginx/html but for many reasons, this may not be the ideal location for your web directory, or you may need to add additional web roots later. This means SELinux might intervene and prevent those new locations from being accessible to the web server.
We can easily simulate this issue by changing the default web root to another common location for website files: /var/www/html.
# Modify the default configuration for NGINX
# We'll change the web root, as shown in bold below$> vi /etc/nginx/conf.d/default.confserver {
listen 80;
server_name localhost;
#charset koi8-r;
#access_log /var/log/nginx/host.access.log main; location / {
#root /usr/share/nginx/html;
root /var/www/html;
index index.html index.htm;
}
...# Reload NGINX config for our settings to take effect
$> nginx -s reload
We’ll put an index file in the new web root location for good measure, just so that we can be sure we’re seeing our changes take effect. We’ll first need to create the /var/www/html sub-directories as they don’t exist by default in CentOS.
$> mkdir -p /var/www/html
$> vi /var/www/html/index.html<html>
<body>
<h1>Hello, World!</h1>
</body>
</html># Save the file
:wq
If we visit our server IP again, we should see our hello world page. But we don’t.
So, what’s going on here? SELinux recognizes that NGINX has access to it’s own folders that are created during install, but it’s taking issue with the fact that NGINX is now trying to access the /var/www/html folder and blocking us.
We can review permissions, but we’ll see NGINX’s original path /usr/share/nginx/index.html is all owned by root, just like our /var/www/html/index.html path and file. The SELinux policy is explicitly limiting NGINX’s access to our new path.
We can confirm this by reviewing the audit log, which we’ll cover in the next section.
We can also confirm this by temporarily disabling SELinux. But wait! Didn’t we decide that was a bad idea? Yes, we did — but we can use the permissive setting to simulate disabling SELinux. However, it’s important to remember to re-enable enforcement after we test.
…we can use the permissive setting to simulate disabling SELinux. However, it’s important to remember to re-enable enforcement after we test.
To set SELinux into the permissive state we can do the following:
$> setenforce 0If we refresh our server IP web page again we’ll see the 403 error has disappeared and we can now see our Hello, World! index page is working. Since we just temporarily stopped SELinux enforcement and suddenly our page works, we can be reasonably certain an SELinux policy was at fault.
We can now use our audit tools to review the audit log and create some custom policy settings that will allow everything to function properly.
First, let’s set the enforcement policy back to enforcing.
$> setenforce 1Reviewing the Audit Log
Earlier we installed two Linux command line tools policscoreutils-python and setroubleshoot. We can use these to review our audit log and, in the next step, create custom policies to overcome our SELinux roadblock.
To review the audit log navigate to the audit log directory, then run a simple grep command.
$> cd /var/log/audit
$> cat audit.log | grep failWe’re not really auditing the log quite yet. We’re looking for instances of the word “fail” indicating SELinux blocked some action. You’ll notice that some of these include the term “AVC” and some of those include “nginx” — this is what we’re hunting for.
type=AVC msg=audit(1538439060.411:4960): avc: denied { open } for pid=10007 comm="nginx" path="/var/www/html/index.html" dev="vda1" ino=25250737 scontext=system_u:system_r:httpd_t:s0 tcontext=unconfined_u:object_r:var_t:s0 tclass=fileI won’t bore you with the details, but this log has a lot of valuable information that our audit tools can pick up on to create a policy to allow this action. Let’s run this through the audit tools next.
To actually audit this log, use the command audit2why which will give us a little more human-readable formatted explanation of what’s going on.
# Using audit2why$> grep nginx /var/log/audit/audit.log | audit2why type=AVC msg=audit(1538439060.411:4960): avc: denied { open } for pid=10007
comm="nginx" path="/var/www/html/index.html" dev="vda1"
ino=25250737 scontext=system_u:system_r:httpd_t:s0
tcontext=unconfined_u:object_r:var_t:s0 tclass=file
Was caused by:
Missing type enforcement (TE) allow rule.
You can use audit2allow to generate a loadable module to allow this access.
This is telling us that SELinux blocked this because there isn’t a rule allowing such an action, and such an action is blocked by default. If we want to allow this action, we can do exactly what it says on the last line — use audit2allow to create a loadable module (which will install a policy for us) and allow this access.
Before we do that, let’s discuss briefly why we don’t just jump to audit2allow in the first place. In some cases, you may believe SELinux is at fault when instead you have a simple permissions issue. Proper Linux permissions management is outside the scope of this tutorial, but I will show you a message similar to what you might see when this is the case.
If you see this message it probably means you need to check something besides SELinux for the cause of your issue.
# Example output when SELinux policy exists for this issue$> grep nginx audit.log | audit2whytype=AVC msg=audit(1538439136.849:4963): avc: denied { open } for pid=10007 comm="nginx" path="/var/www/html/index.html" dev="vda1" ino=25250737 scontext=system_u:system_r:httpd_t:s0 tcontext=unconfined_u:object_r:var_t:s0 tclass=file Was caused by:
Unknown - would be allowed by active policy
Possible mismatch between this policy and the one under which the audit message was generated. Possible mismatch between current in-memory boolean settings vs. permanent ones.
Using audit2allow To Create a Custom Policy Module
Using audit2allow is similar to how we use audit2why, in fact we’ll use almost the same command format. Before we move on to running the command, let’s review some critical points.
Every good server admin monitors their work periodically to make sure it’s effective, and this is no different.
It’s important to remember that you may need to do this multiple times, which is why I mentioned monitoring the server over the next few days: it’s entirely possible your web server application (NGINX in this case) may take actions that later trigger an SELinux response.
you may need to do this multiple times
In my experience, once you get everything running, there may be a few times after this, maybe three or four instances, where you need to create additional custom policy modules after your initial attempts once you finally get your app or site working. If you aren’t seeing additional failure logs from NGINX in /var/log/audit/audit.log then you’ve resolved the conflicts.
If you aren’t seeing additional failure logs in
/var/log/audit/audit.logthen you’ve resolved the conflicts.
Now we can move on to learning to use audit2allow. Let’s review the command syntax first.
# Let's review the command syntax
grep [keyword] audit.log | audit2allow -M [name of our policy]
| |
The keyword is what The name of our policy
we're searching the log for. can be whatever we want.# Example using "nginx" as our keyword.
$> grep nginx audit.log | audit2allow -M nginxpolicy
This command will create two files, only one of which we need to worry about, and it will also inform you how to use the file using the semodule command. Let’s put it to use.
$> grep nginx audit.log | audit2allow -M nginxpolicy
******************** IMPORTANT ***********************
To make this policy package active, execute:semodule -i nginxpolicy.pp
We can now do exactly as it says, and run the semodule command to install this SELinux policy.
semodule -i nginxpolicy.ppIf you try our test page again using your browser, you may see that it now works. If not, rinse and repeat until you have a working page.
You may want to follow the audit log while refreshing the page — this will show you the most recent logs and help to more easily identify the error. You can use tail to do this.
$> tail -f /var/log/audit/audit.logNow when you refresh the page, the most recent SELinux conflict will be output to the shell. You can pull a keyword from this error to use when running audit2why and audit2allow to target this issue when creating your policy module.
Not So Bad, Eh?
We only covered the very basics of SELinux management in this tutorial, but this may very well be all you need if you’re only running web apps and sites on your server. I’ll try to cover this in more detail if people request.
I hope this allowed you to configure your server with SELinux enforcing it’s security polices successfully. Let me know what you think in the comments, and if this article helped you, or if you ran into trouble — please let me know!
For additional reading on SELinux, get it from the horse’s mouth over at the CentOS wiki — https://wiki.centos.org/HowTos/SELinux.
