Skip to main content

Configuring the NGINX Server – HTTP Virtual Hosts / Rewrites / Custom Error Pages / Directives

Hands-On Lab

 

Photo of Tom Dean

Tom Dean

Linux Training Architect II

Length

01:00:00

Difficulty

Intermediate

Before we can start building our world-changing website or application on LEMP, we have to lay the foundation - the stack. In this hands-on lab, we will walk through configuring NGINX on Ubuntu Linux. We will explore configuring HTTP (non-secure) virtual hosts, rewrites, custom error pages, and directives.

Completing this lab will provide a good understanding of how to implement these NGINX concepts on Ubuntu Linux.

What are Hands-On Labs?

Hands-On Labs are scenario-based learning environments where learners can practice without consequences. Don't compromise a system or waste money on expensive downloads. Practice real-world skills without the real-world risk, no assembly required.

Configuring the NGINX Server - HTTP Virtual Hosts / Rewrites / Custom Error Pages / Directives

Introduction

Before we can start building our world-changing website or application on LEMP, we have to lay the foundation - the stack. In this hands-on lab, we will walk through configuring NGINX on Ubuntu Linux. We will explore configuring HTTP (non-secure) virtual hosts, rewrites, custom error pages, and directives.

Completing this lab will provide a good understanding of how to implement these NGINX concepts on Ubuntu Linux.

The Scenario

Big State College (BSC) is a Large Ten Conference school in a Midwestern state. BSC is looking to deploy a centralized web hosting service using the LEMP stack.

As the engineers tasked with executing this project, we will be configuring HTTP virtual hosts, rewrites, custom error pages, and directives on an Ubuntu Linux server. Let's begin!

Logging In

Use the credentials provided on the hands-on lab overview page, and log in as cloud_user. We need root privileges for everything in this lab, so once we're logged in we can get them with sudo su -.

Create an HTTP Virtual Host Configuration

First, change to the /etc/nginx/sites-available directory so we can add the new virtual host configuration block:

cd /etc/nginx/sites-available

We're going to copy the configuration file related to the virtual host for site3.bigstatecollege.edu into a new one:

cp site3.bigstatecollege.edu.conf site4.bigstatecollege.edu.conf

Edit the New HTTP Virtual Host Configuration

Now we're going to edit that new configuration file for site4:

vi site4.bigstatecollege.edu.conf

Change the port that the virtual host is listening on to 8081, either manually or with search and replace in Vim:

:%s/8090/8081

The listen line should look like this when we're done:

listen 8081;

Also, change the site3 entries for the root directory and the server_name to point to site4 instead. Save and exit the file.

Activate and Test the New Virtual Host Configuration

Create a soft link in /etc/nginx/sites-enabled to "activate" the configuration:

ln -s /etc/nginx/sites-available/site4.bigstatecollege.edu.conf /etc/nginx/sites-enabled/site4.bigstatecollege.edu.conf

Validate and reload the NGINX configuration:

nginx -t
systemctl reload nginx

Test the virtual host:

curl http://site4.bigstatecollege.edu:8081

We should see the following:

Welcome to site4.bigstatecollege.edu!

Explore the Legacy Download Server

There's a download directory for legacy website downloads, and a virtual host (port 8084). We wish to present this directory as http://www.bigstatecollege.edu/downloads/. Let's take a quick look at them:

ls -la /var/www/download_files

We can see three files (file1.txt, file2.txt, and file3.txt) in there. We can get to file1.txt via http://downloads.bigstatecollege.edu:8084/file1:

curl http://downloads.bigstatecollege.edu:8084/file1.txt

Just replace file1 in the curl command with file2 or file3 to see the others.

Create a Rewrite for the Legacy Download Server

Edit the configuration file:

vi bigstatecollege.edu.conf

Add the following section:

        location /downloads {
                rewrite ^(/downloads)/(.*)$ http://downloads.bigstatecollege.edu:8084/$2 permanent;
                return 403;
        }

This will pass the file name in the /downloads part of the URL to the new URL as the second argument ($2).

Test the Rewrite

Validate and reload the NGINX configuration:

nginx -t
systemctl reload nginx

Test the rewrite:

curl http://www.bigstatecollege.edu/downloads/file1.txt

That didn't work. Let's try again and tell curl to follow the location change:

curl -L http://www.bigstatecollege.edu/downloads/file1.txt

We can try this same command, replacing file1 with file2 or file3, to see the other files.

To see what's going on behind the scenes, use the '-I' switch with curl:

curl -I http://www.bigstatecollege.edu/downloads/file1.txt

The Location information points to http://downloads.bigstatecollege.edu:8084/file1.txt.

View the Custom Error Page

We've provided a custom 404 error page on the lab server that is branded for bigstatecollege.edu. This file is /var/www/html/BSC_404.html. We can take a look at it with this:

cat /var/www/html/BSC_404.html

Try accessing a file that doesn't exist with curl:

curl http://www.bigstatecollege.edu/nofile.txt

We will get a generic error page.

Configure the Custom Error Page

To use our custom error page instead, we will need to configure it in the bigstatecollege.edu virtual host server configuration file. Edit the file:

vi bigstatecollege.edu.conf

Now we can add a section of code to configure a custom error page to show when there is a 404 error:

        error_page 404 /BSC_404.html;
        location = /BSC_404.html {
                root /var/www/html;
                internal;
        }

Save and exit the configuration file.

Test the Custom Error Page

Validate and reload the NGINX configuration:

nginx -t
systemctl reload nginx

Try accessing the file that doesn't exist again:

curl http://www.bigstatecollege.edu/nofile.txt

We should see the custom error page now.

Exploring the Application Servers

Big State College is building an application backend, which they want to proxy under http://www.bigstatecollege.edu/app. The backend application servers are already up and running. We can validate this using curl:

curl http://app1.bigstatecollege.edu:8085
curl http://app2.bigstatecollege.edu:8086
curl http://app3.bigstatecollege.edu:8087

Configuring the Upstream Directive for the Application Servers

We need to define a group of (application) servers using the upstream directive. Let's edit our configuration file again:

vi bigstatecollege.edu.conf

Add these lines to the beginning of the file:

upstream bscapp  {
   server app1.bigstatecollege.edu:8085;
   server app2.bigstatecollege.edu:8086 backup;
   server app3.bigstatecollege.edu:8087 backup;
}

Now add a location block for the app directory (between the / and /downloads blocks):

        location /app {
                proxy_pass http://bscapp/;
        }

Save and exit the file.

Restart NGINX and Test the Upstream

Validate and reload the NGINX configuration:

nginx -t
systemctl reload nginx

Test the upstream with this:

curl http://www.bigstatecollege.edu/app

We will see that app1.bigstatecollege.edu is serving requests. The other two servers are backups right now.

Mark the app1 Server as Down

What happens if app1 goes down? Let's simulate such an outage. Edit the configuration again:

vi bigstatecollege.edu.conf

Mark the app1 server as down in the upstream configuration:

upstream bscapp  {
   server app1.bigstatecollege.edu:8085 down;
   server app2.bigstatecollege.edu:8086 backup;
   server app3.bigstatecollege.edu:8087 backup;
}

Now let's see if the backup servers take over. Validate and reload the NGINX configuration (nginx -t and systemctl reload nginx), then and test the upstream again:

curl http://www.bigstatecollege.edu/app

We will see that NGINX pulls from both the app2 and app3 servers.

Enable the app1 Server and Test

Let's put app1 back in the lineup. Edit the configuration file and remove the down from app1 in the bscapp group:

upstream bscapp  {
   server app1.bigstatecollege.edu:8085;
   server app2.bigstatecollege.edu:8086 backup;
   server app3.bigstatecollege.edu:8087 backup;
}

Save, exit, validate and reload the NGINX configuration. Test the upstream:

curl http://www.bigstatecollege.edu/app

We should get Welcome to app1.bigstatecollege.edu!. The app2 and app3 servers are only acting as backups.

Conclusion

We've gone through several aspects of NGINX configuration, all of which are very valuable skills to have when running a LEMP stack on Ubuntu. Congratulations!