« Signs of a forthcoming release of Engarde Linux?

Installing a Web Application on Engarde Secure Linux


Once you've read this article you will have learned how to install a PHP Web Application on a server running Engarde Secure Linux.
For the sake of this article, we will assume that you are running version 3.0.22 or later of Engarde Linux with SELinux in enforcing mode and that you have already installed the following packages: apache, MySQL-server, php5 and php5-mysql. Obviously we assume that you have root access as well.

If you don't have your Engarde server up and running yet then check out the
Engarde Secure Linux 3.0 - Quick Start Guide to get you up to speed.

I will use the PHP blog WordPress as an example for this article, but reading it should give you the necessary knowledge to install any PHP application.

Let us begin...

Creating the virtual host

Load up your webtool and go to "Services->World Wide Web Management", then select "Module->Create New Virtual Host".

The form is self-explanatory but we'll go through it anyway.
Enter the hostname and the external IP-address of your server, don't forget to include "www" in your hostname.
Leave Use SSL as it is and enter your email in Admin Email. Pretty basic.

Webmaster and Group will be used to set file ownership, where Webmaster is the user. There are a multitude of opinions on how to set these up, and all claim to be the most secure. I will leave it up to you to select what works best for you. To continue the guide I will just assume that we have the user 'joe' that is a member of the group 'staff' and use that.

Since WordPress, like most web applications, requires a database we should continue by selecting 'Yes' in the Create Database field.
Unfortunatly the webtool doesn't allow us to name databases ourself. By default it will get named after your hostname, so if your hostname is www.example.com you database will be named www_example_com. If you don't like this you can always setup the database manually through the command line mysql client.

We proceed by entering a name and a password for the database user. This should not be an existing user as the webtool will create one for us. Each application should have it's own database and user whenever possible to minimize damages in case something goes terribly wrong. Since the username and password will only be used by the application I tend to use random strings for both. It's easier to use a password generator than to make something up yourself. The username should only consist of letters and numbers while the password should use symbols as well. There is one caveat, the webtool can't handle form input with " or ' in them, so make sure to remove them from any generated strings. Write down the username and password on a piece of paper for later reference.

SELinux, the booleans

Booleans in SELinux are switches that activate or deactivate security restrictions on your Linux system set in place by the current SELinux policy.
On the SELinux Control Console, in the webtool, we read 'Generally speaking when you activate a boolean you slightly decrease the security of your machine'. While this is true, you shouldn't be alarmed.

Go to "System->SELinux Control Console" and activate the booleans "httpd_script_remote", "httpd_write_content_dir" and "httpd_write_tmp_dir".
These are inactive by default so make sure to activate them for "Boot" as well as for "Current". If you don't activate them for "Boot" the settings will revert to inactive if the system should reboot.

  • What exactly do these booleans do and why should I activate them?
  • httpd_script_remote: This allows Apache to establish TCP connections with remote systems. WordPress uses this functionality to ping and to check for software updates. Certain plugins might require this as well. If you don't need this functionality then you can safely leave it inactive.
  • httpd_write_content_dir: This allows Apache to read and write files in the document root. Again using WordPress as example, this is required for media upload to work. It will also allow the built in file editor to work. Using file permissions and attributes we restrict which files and folders that can be written. More about this in the next section, 'Files, Permissions and Security Context'.
  • httpd_write_tmp_dir: This allows Apache to write to the system tmp directory. This is required for file uploads.

When this step is complete you can close the webtool, open up your favorite SSH client and login to your system.
In the next and final step we will setup our files and permissions. Some of the actions require root access so you might as well open a root shell.

Files, Permissions and Security Context

In order for Apache to serve up your web documents they obviously need to reside in your virtual hosts document root. So the first step is to move them there. All virtual hosts created through the webtool get a document root in "/home/httpd/". The directory structure is as follows:

  • www.example.com-80/
    • html/
    • cgi-bin/
    • logs/

Move the application files in to the document root:

#cd /home/httpd/www.example.com-80/html
#mv ~joe/wordpress/* .

The next requirement is that the files and directories are all readable by Apache. They should be by default but we make sure by typing:

#find . -type d -exec chmod 755 {} \;
#find . -type f -exec chmod 644 {} \;

The first line will find all directories and set their permission to u+rwx, g+rx, o+rx.
Similarly, the following line will set all files to u+rw, go+r.

If you want your web application to be able to upload files you have to give the web server additional permissions to the upload directory.
In our example application, WordPress, the upload directory is "wp-content/upload/".

#chown joe:webd wp-content/upload/
#chmod g+w wp-content/upload/

We start by changing the ownership of the upload directory to joe:webd. "webd" is the default user and group that apache is run as on Engarde Linux.
We then continue by altering the permissions to give the group write access. This ensures that other processes and users on the system still can't write to the directory but you and the web application can. If you want the built in editor in WordPress to work you need to grant write permission to the themes folder as well. But I wouldn't recommend doing that.

On a system without SELinux this would have been our final step and Apache would happily be serving our files.
SELinux however, adds another security measure that we need to address, Security Context.

All system access controls are based on some type of access control attribute. In SELinux, the access control attribute is called a security context.
The inner workings of SELinux are to vast a subject for this article so without going in to deep I'll just say that a security context has three elements: user, role and type identifiers. All files and processes have a single security context associated with them, and for the security context to be valid it must have a valid user, role and type identifier. On a system running Engarde Linux, files are required to have the security context "system_u:object_r:httpd_content_t" in order for Apache to access them.

By typing ls -Z in our web root we see the security context of our files. You should see something like this:

#ls -Z index.php
-rw-r--r--  joe staff user_u:object_r:user_home_t index.php

Our files currently have the security context "user_u:object_r:user_home_t" which they inherited from the user home directory.
We need to change the security context before Apache can serve the files. Fortunatly doing so is quite easy.

#chcon -R -u system_u -r object_r -t httpd_content_t *
#ls -Z index.php
-rw-r--r--  joe staff system_u:object_r:httpd_content_t index.php

That's it, your web files are now accessible by Apache.

Wrapping up

Now that the files are accessible all that remains is configuring your web application, in WordPress this is done by editing the file wp-config.php.
You need to replace the values of DB_NAME, DB_USER and DB_PASSWORD with the database name, user and password you created in step 1.

define('DB_NAME', 'www_example_com');
/** MySQL database username */
define('DB_USER', 'myuser');

/** MySQL database password */
define('DB_PASSWORD', 'mypassword');

Now to test if it all worked, point your web browser towards your site and you should see the application in all it's glory.

Hopefully I didn't disappoint you

In the first sentence of this article I promised that you would learn how to install a web application on a system running Engarde Linux, hopefully I didn't disappoint you. I realize that the SELinux stuff is still very confusing but the little we covered is all you need to know in order to make most web applications work. If you want to learn more about SELinux there are several sources out there. You could start with the Engarde Wiki but at the time of writing this article, it is not very comprehensive. As usual google is your friend.

The most common problem with setting up a website (or any other service for that matter) on Engarde Linux is forgetting or not knowing about the security context. So if you remember only one thing from this article, let it be that.

That is all for this time and I hope you enjoyed the article.