A practical guide to Fedora and Red Hat Enterprise Linux, 7th Edition (2014)

Server-Generated Directory Listings (Indexing)

When a client requests a directory, the Apache configuration determines what is returned to the client. Apache can return a file as specified by the DirectoryIndex directive (page 944), a directory listing if no file matches DirectoryIndex and the Options Indexes directive (page 957) is set, or an error message if no file matches DirectoryIndex and Options Indexes is not set. Figure 26-1 shows a server-generated directory listing.

Figure 26-1 A server-generated directory listing

Virtual Hosts

Apache supports virtual hosts, which means that one instance of Apache can respond to requests directed to multiple IP addresses or hostnames as though it were multiple servers. Each IP address or hostname can then provide different content and be configured differently.

There are two types of virtual hosts: host-by-name (also called host-based) and host-by-IP. Host-by-name relies on the FQDN the client uses in its request to Apache—for example, www.example.com versus www2.example.com. Host-by-IP examines the IP address the host resolves as and responds according to that match.

Host-by-name is handy if there is only one IP address, but Apache must support multiple FQDNs. Although you can use host-by-IP if a given Web server has aliases, Apache should serve the same content regardless of which name is used.

The NameVirtualHost directive specifies which IP address supports host-by-name virtual hosting; the ServerName (or ServerAlias) directive must match the client request to match that virtual host. Without a NameVirtualHost directive, the virtual host is a host-by-IP virtual host; the ServerName directive specifies the name the server uses to identify itself.

You can specify many virtual hosts for a single instance of Apache.

Examples

The following examples of host-by-name virtual hosting use wildcards (*) to remain as flexible as possible. You might want to replace the wildcards with the IP address of the server for more precise control when Apache is serving multiple virtual hosts.

The first <VirtualHost> container sets up host-by-name for the site named example.com. This virtual host handles requests that are directed to example.com. The ServerAlias directive allows it to also process requests directed to www.example.com.

<VirtualHost *>
ServerName example.com
ServerAlias www.example.com
ServerAdmin webmaster@example.com
DocumentRoot /var/www/html/example.com
CustomLog /var/log/httpd/example.com.log combined
ErrorLog /var/log/httpd/example.com.err
</VirtualHost>

The next example is similar to the previous one. It adds a Directory directive that prevents remote users (users not coming from the 192.168. subnet) from accessing the Web site.

<VirtualHost *>
ServerName intranet.example.com
ServerAdmin webmaster@example.com
DocumentRoot /var/www/html
ErrorLog /var/log/httpd/intra.error_log
CustomLog /var/log/httpd/example.com.log combined
<Directory /var/www/html>
Order deny,allow
Deny from all
Allow from 192.168. # allow from private subnet only
</Directory>
</VirtualHost>

The next example sets up two virtual hosts. The VirtualHost containers accept all traffic directed to the server by specifying *. The ServerName directives accept traffic for sam.example.com (or the alias www.example.com/sam) and mail.example.com. The first virtual host serves documents from Sam’s public_html directory; the second is a Webmail server with its content at /var/www/html/squirrelmail. This example works because all three addresses resolve to the IP address of the server.

NameVirtualHost *:
<VirtualHost *>
ServerName sam.example.com
ServerAlias www.example.com/sam
ServerAdmin webmaster@example.com
DocumentRoot /home/sam/public_html
</VirtualHost>

<VirtualHost *:>
ServerName mail.example.com
ServerAdmin webmaster2@example.com
DocumentRoot /var/www/html/squirrelmail
</VirtualHost>

If the user specifies an IP address and not a URI, that address might match more than one of the virtual hosts, as in the example. In this case, Apache serves the virtual host that best matches. If none of the virtual host addresses matches the IP address better than another, Apache serves the first virtual host. In the preceding example, both virtual hosts match an IP address the same way; neither is a better match, so Apache serves the first virtual host (sam.example.com). If mail.example.com was defined as <VirtualHost 192.168.1.102> and a user specified that IP address, Apache would serve mail.example.com because it is a better match for the IP address than the wildcard that the other virtual host specifies.

The next example shows VirtualHost containers for a host-by-IP server. The example assumes that 111.111.0.0 and 111.111.0.1 point to the local server. Here each virtual host has its own IP/port combination. The third virtual host is distinguished from the first by the port that a request comes in on.

<VirtualHost 111.111.0.0:80>
DocumentRoot /var/www/html/www0
</VirtualHost>

<VirtualHost 111.111.0.1:80>
DocumentRoot /var/www/html/www1
</VirtualHost>

<VirtualHost 111.111.0.0:8080>
DocumentRoot /var/www/html/www2
Listen 8080
</VirtualHost>

The final example sets up a virtual server for Webmail that can be accessed only over SSL. To use this example you must create an SSL certificate (page 970).

<VirtualHost mail.example.com:80>
Redirect permanent / https://mail.example.com/
</VirtualHost>
<VirtualHost mail.example.com:443>
ServerName mail.example.com
ServerAdmin postmaster@example.com
DocumentRoot /var/www/html/mail.example.com
ErrorLog /var/log/httpd/mail.example.com.err
CustomLog /var/log/httpd/mail.example.com.log combined
SSLEngine On
SSLCertificateFile /etc/pki/tls/certs/apache.pem
</VirtualHost>

Troubleshooting

If the browser does not display the information you expect, make sure it is not displaying a cached version of the page. Try clearing the browser’s cache and reloading the page. Also make sure that Apache has permission to read the files it is serving and the scripts it is running.

The httpd service checks the syntax of the Apache configuration files and logs an error if there is a problem. You can also call apachectl directly to check the syntax:

$ apachectl configtest
Syntax OK

Once you start the httpd daemon, you can confirm Apache is working correctly by pointing a browser on the local system at http://localhost/. From a remote system, use http://server/, substituting the hostname or IP address of the server for server. In response, Apache displays the Fedora/RHEL test page (page 937) unless you have added an index file or changed the default virtual host.

If the browser does not display the test page, it will display one of two errors: Connection refused or an error page. If it displays Connection refused, make sure port 80 is not blocked by a firewall (page 934), check that SELinux (page 934) is set up properly, and check that the server is running:

# systemctl status httpd.service
httpd.service - The Apache HTTP Server
Loaded: loaded (/usr/lib/systemd/system/httpd.service; enabled)
Active: active (running) since ...

If the server is running, confirm that you did not specify a port other than 80 in a Listen directive. If you did, the URI you specify in the browser must reflect this port number (http://localhost:port specifies port port). Otherwise, check the error log (/var/log/httpd/error_log) for information about what is not working.

To verify the browser is not at fault, use telnet to connect to port 80 of the server:

$ telnet www.example.com 80
Trying 192.0.34.166...
Connected to www.example.com.
Escape character is '^]'.
CONTROL-]
telnet> quit
Connection closed.

If telnet displays Connection refused, it means the local system cannot connect to the server.

Modules

Apache is a skeletal program that relies on external modules, called DSOs (dynamic shared objects), to provide most of its functionality. In addition to the modules included with Fedora/RHEL, many other modules are available. For more information see httpd.apache.org/modules and httpd.apache.org/docs/2.4/mod.

Following is a list of some of the modules that are available under Apache.

actions (mod_actions.so) Allows execution of CGI scripts based on the request method.

alias (mod_alias.so) Allows outside directories to be mapped to DocumentRoot.

asis (mod_asis.so) Allows sending files that contain their own headers.

auth_basic (mod_auth_basic.so) Provides user authentication via .htaccess.

auth_digest (mod_auth_digest.so) Uses MD5 digest for authentication.

authn_anon (mod_authn_anon.so) Provides anonymous user access to restricted areas.

authn_dbd (mod_authn_dbd.so) Uses SQL files for authentication.

autoindex (mod_autoindex.so) Allows directory indexes to be generated.

cgi (mod_cgi.so) Allows the execution of CGI scripts.

dav (mod_dav.so) Allows Distributed Authoring and Versioning.

dav_fs (mod_dav_fs.so) Provides a filesystem for mod_dav.

dir (mod_dir.so) Allows directory redirects and listings as index files.

env (mod_env.so) Allows CGI scripts to access environment variables.

expires (mod_expires.so) Allows generation of Expires HTTP headers.

headers (mod_headers.so) Allows customization of request and response headers.

include (mod_include.so) Provides server-side includes (SSIs).

info (mod_info.so) Allows the server configuration to be viewed.

log_config (mod_log_config.so) Allows logging of requests made to the server.

mime (mod_mime.so) Allows association of file extensions with content.

mime_magic (mod_mime_magic.so) Determines MIME types of files.

negotiation (mod_negotiation.so) Allows content negotiation.

proxy (mod_proxy.so) Allows Apache to act as a proxy server.

proxy_connect (mod_proxy_connect.so) Allows connect request handling.

proxy_ftp (mod_proxy_ftp.so) Provides an FTP extension proxy.

proxy_http (mod_proxy_http.so) Provides an HTTP extension proxy.

rewrite (mod_rewrite.so) Allows on-the-fly URI rewriting based on rules.

setenvif (mod_setenvif.so) Sets environment variables based on a request.

speling (mod_speling.so) Auto-corrects spelling if the requested URI has incorrect capitalization and one spelling mistake.

status (mod_status.so) Allows the server status to be queried and viewed.

unique_id (mod_unique_id.so) Generates a unique ID for each request.

userdir (mod_userdir.so) Allows users to have content directories (public_html).

usertrack (mod_usertrack.so) Allows tracking of user activity on a site.

vhost_alias (mod_vhost_alias.so) Allows the configuration of virtual hosting.

mod_cgi and CGI Scripts

The CGI (Common Gateway Interface) allows external application programs to interface with Web servers. Any program can be a CGI program if it runs in real time (at the time of the request) and relays its output to the requesting client. Various kinds of scripts, including shell, Perl, Python, and PHP, are the most commonly encountered CGI programs because a script can call a program and reformat its output in HTML for a client.

Apache can handle requests for CGI programs in several different ways. The most common method is to put a CGI program in the cgi-bin directory and then enable its execution from that directory only. The location of the cgi-bin directory, as specified by the ScriptAlias directive (page958), is /var/www/cgi-bin. Alternately, an AddHandler directive (page 952) can identify the filename extensions of scripts, such as .cgi or .pl, within the regular content (e.g., AddHandler cgi-script .cgi). If you use AddHandler, you must also specify the ExecCGI option in an Options directive within the appropriate <Directory> container. The mod_cgi module must be loaded to access and execute CGI scripts.

The following Perl CGI script displays the Apache environment. This script should be used for debugging only because it presents a security risk if remote clients can access it:

#!/usr/bin/perl
##
## printenv -- demo CGI program that prints its environment
##

print "Content-type: text/plain\n\n";
foreach $var (sort(keys(%ENV))) {
$val = $ENV{$var};
$val =~ s|\n|\\n|g;
$val =~ s|"|\\"|g;
print "${var}=\"${val}\"\n";
}

mod_ssl

SSL (Secure Sockets Layer), which is implemented by the mod_ssl module, has two functions: It allows a client to verify the identity of a server and it enables secure two-way communication between a client and a server. SSL is used on Web pages in conjunction with forms that require passwords, credit card numbers, or other sensitive data.

Apache uses the HTTPS protocol—not HTTP—for SSL communication. When Apache uses SSL, it listens on a second port (443 by default) for a connection and performs a handshaking sequence before sending the requested content to the client.

Server verification is critical for financial transactions: You do not want to give your credit card number to a fraudulent Web site posing as a known company. SSL uses a certificate to positively identify a server. Over a public network such as the Internet, the identification is reliable only if the certificate contains a digital signature from an authoritative source such as VeriSign or Thawte. SSL Web pages are denoted by a URI beginning with https://.

Data encryption prevents malicious users from eavesdropping on Internet connections and copying personal information. To encrypt communication, SSL sits between the network and an application and encrypts communication between the server and the client.

Setting Up mod_ssl

You must install the mod_ssl package to run SSL. The /etc/httpd/conf.d/ssl.conf file configures and loads mod_ssl. The first few directives in this file instruct Apache to listen on port 443, and set various parameters for SSL operation. About a third of the way through the file is a section labeled SSL Virtual Host Context that sets up virtual hosts (page 965).

As with any virtual host, a virtual host for SSL holds directives such as ServerName and ServerAdmin that need to be configured. In addition, it holds some SSL-related directives. See the example on page 967.

Using a Self-Signed Certificate for Encryption

If you require SSL for encryption and not verification—that is, if the client already trusts the server—you can generate and use a self-signed certificate, bypassing the time and expense involved in obtaining a digitally signed certificate. Self-signed certificates generate a warning when you connect to the server: Most browsers display a dialog box that allows you to examine and accept the certificate. The sendmail daemon also uses certificates (page 765).

The self-signed certificate depends on two files: a private key and the certificate. The location of each file is specified in /etc/httpd/conf.d/ssl.conf:

# grep '^SSLCertificate' /etc/httpd/conf.d/ssl.conf
SSLCertificateFile /etc/pki/tls/certs/localhost.crt
SSLCertificateKeyFile /etc/pki/tls/private/localhost.key

The following example creates a self-signed certificate. To generate the private key that the encryption relies on, cd to /etc/pki/tls/certs and enter a make command:

# cd /etc/pki/tls/certs
# make localhost.key
umask 77 ; \
/usr/bin/openssl genrsa -aes128 2048 > localhost.key
Generating RSA private key, 2048 bit long modulus
.+++
....................+++
e is 65537 (0x10001)
Enter pass phrase:
Verifying - Enter pass phrase:

The preceding command generates a file named localhost.key that is protected by the passphrase you entered: You will need this passphrase to start the server. Keep the localhost.key file secret.

The next command generates the certificate. This process uses the private key you just created. You need to supply the same passphrase you entered when you created the private key.

# make localhost.crt
umask 77 ; \
/usr/bin/openssl req -utf8 -new -key localhost.key -x509 -days 365 -out
localhost.crt -set_serial 0
Enter pass phrase for localhost.key:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [GB]:US
State or Province Name (full name) [Berkshire]:California
Locality Name (eg, city) [Newbury]:San Francisco
Organization Name (eg, company) [My Company Ltd]:Sobell Associates Inc.
Organizational Unit Name (eg, section) []:
Common Name (eg, your name or your server's hostname) []:www.sobell.com
Email Address []:mgs@sobell.com

The answers to the first five questions are arbitrary: They can help clients identify a site when they examine the certificate. The answer to the sixth question (Common Name) is critical. Because certificates are tied to the name of the server, you must enter the server’s FQDN accurately. If you mistype this information, the server name and that of the certificate will not match. The browser will then generate a warning message each time a connection is made.

As specified by ssl.conf, Apache looks for the files in the directory that you created them in. Do not move these files. After you restart Apache, the new certificate will be in use.

Notes on Certificates

• As long as the server is identified by the name for which the certificate was issued, you can use the certificate on another server or IP address.

• A root certificate is the certificate that identifies the root certificate authority (root CA). Every browser contains a database of the public keys for the root certificates of the major signing authorities, including VeriSign and Thawte.

• It is possible to generate a root certificate and sign all your server certificates with this root CA. Regular clients can import the public key of the root CA so that they recognize every certificate signed by that root CA. This setup is convenient for a server with multiple SSL-enabled virtual hosts and no commercial certificates. For more information see www.modssl.org/docs/2.8/ssl_faq.html#ToC29.

• A self-signed certificate does not enable clients to verify the identity of the server.

Authentication Modules and .htaccess Files

To restrict access to a Web page, Apache and third parties provide authentication modules and methods that can verify a user’s credentials, such as a username and password. Some modules support authentication against various databases including NIS (page 770) and LDAP (page 786).

User authentication directives are commonly placed in a .htaccess file. A basic .htaccess file that uses the Apache default authentication module (mod_auth) follows. When placed in /var/www/html, this file causes Apache to request a password before a browser can access content in the/var/www/html directory hierarchy. Substitute appropriate values for the local server.

# cat .htaccess
AuthUserFile /var/www/html/.htpasswd
AuthGroupFile /dev/null
AuthName "Browser dialog box query"
AuthType Basic
require valid-user

The /var/www/html/.htpasswd is a typical absolute pathname of a .htpasswd file and Browser dialog box query is the string that the user will see as part of the dialog box that requests a username and password.

The second line of the preceding .htaccess file turns off the group function. The fourth line specifies the user authentication type Basic, which is implemented by the default mod_auth module. The last line tells Apache which users can access the protected directory. The entry valid-usergrants access to the directory to any user whose username appears in the Apache password file and who enters the correct password.

You can put the Apache password file anywhere on the system, as long as Apache can read it. It is safe to put this file in the same directory as the .htaccess file because, by default, Apache will not answer any requests for files whose names start with .ht. However, be sure you have not changed the httpd.conf configuration file to allow Apache to answer requests for files whose names begin with .ht. See page 939 for more information on .htaccess files.

The following command creates (–c) a .htpasswd file with an entry for Sam in the working directory. Omit the –c option to add a user or to change a password in an existing .htpasswd file.

$ htpasswd -c .htpasswd sam
New password:
Re-type new password:
Adding password for user sam

The default httpd.conf file includes an AllowOverride None directive (page 960) for /var/www/html. You must change this directive to at least AllowOverride AuthConfig or remove it to enable Apache to process user authentication directives (such as reading an .htaccess file).