Chapter 36
httpd — Apache Web Server
In this chapter, we will show how to set up a web server running virtual domains and dynamic CGI web pages. HTML is not covered, and you are expected to have some understanding of what HTML is, or at least where to find documentation about it.
36.1 Web Server Basics
In Section 26.2 we showed a simple HTTP session with the telnet command. A web server is really nothing more than a program that reads a file from the hard disk whenever a GET /
389 36.1. Web Server Basics 36. httpd — Apache Web Server
You will also have to create a log file (/usr/local/var/log/sh-httpd.log) and at least one web page (/usr/local/var/sh-www/index.html) for your server to serve. It can contain, say: § ¤
Please visit The Rute Home Page 10 for more info.
¦ ¥Note that the server runs as nobody, so the log file must be writable by the no- body user, and the index.html file must be readable. Also note the use of the get- peername command, which can be changed to PEER="" if you do not have the net- pipes package installed. &I am not completely sure if other commands used here are unavailable on other UNIX systems.-. § ¤ #!/bin/sh VERSION=0.1 NAME="ShellHTTPD" DEFCONTENT="text/html" 5 DOCROOT=/usr/local/var/sh-www DEFINDEX=index.html LOGFILE=/usr/local/var/log/sh-httpd.log
log() { 10 local REMOTE_HOST=$1 local REFERRER=$2 local CODE=$3 local SIZE=$4
15 echo "$REMOTE_HOST $REFERRER - [$REQ_DATE] \ \"${REQUEST}\" ${CODE} ${SIZE}" >> ${LOGFILE} }
print_header() { 20 echo -e "HTTP/1.0 200 OK\r" echo -e "Server: ${NAME}/${VERSION}\r" echo -e "Date: ‘date‘\r" }
25 print_error() { echo -e "HTTP/1.0 $1 $2\r"
390 36. httpd — Apache Web Server 36.1. Web Server Basics
echo -e "Content-type: $DEFCONTENT\r" echo -e "Connection: close\r" echo -e "Date: ‘date‘\r" 30 echo -e "\r" echo -e "$2\r" exit 1 }
35 guess_content_type() { local FILE=$1 local CONTENT
case ${FILE##*.} in 40 html) CONTENT=$DEFCONTENT ;; gz) CONTENT=application/x-gzip ;; *) CONTENT=application/octet-stream ;; esac
45 echo -e "Content-type: $CONTENT" }
do_get() { local DIR 50 local NURL local LEN
if [ ! -d $DOCROOT ]; then log ${PEER} - 404 0 55 print_error 404 "No such file or directory" fi
if [ -z "${URL##*/}" ]; then URL=${URL}${DEFINDEX} 60 fi
DIR="‘dirname $URL‘" if [ ! -d ${DOCROOT}/${DIR} ]; then log ${PEER} - 404 0 65 print_error 404 "Directory not found" else cd ${DOCROOT}/${DIR} NURL="‘pwd‘/‘basename ${URL}‘" URL=${NURL} 70 fi
if [ ! -f ${URL} ]; then log ${PEER} - 404 0 print_error 404 "Document not found" 75 fi
print_header guess_content_type ${URL} LEN="‘ls -l ${URL} | tr -s ’ ’ | cut -d ’ ’ -f 5‘" 80 echo -e "Content-length: $LEN\r\n\r" log ${PEER} - 200 ${LEN}
391 36.1. Web Server Basics 36. httpd — Apache Web Server
cat ${URL} sleep 3 } 85 read_request() { local DIRT local COMMAND
90 read REQUEST read DIRT
REQ_DATE="‘date +"%d/%b/%Y:%H:%M:%S %z"‘" REQUEST="‘echo ${REQUEST} | tr -s [:blank:]‘" 95 COMMAND="‘echo ${REQUEST} | cut -d ’ ’ -f 1‘" URL="‘echo ${REQUEST} | cut -d ’ ’ -f 2‘" PROTOCOL="‘echo ${REQUEST} | cut -d ’ ’ -f 3‘"
case $COMMAND in 100 HEAD) print_error 501 "Not implemented (yet)" ;; GET) do_get 105 ;; *) print_error 501 "Not Implemented" ;; esac 110 }
# # It was supposed to be clean - without any non-standard utilities # but I want some logging where the connections come from, so 115 # I use just this one utility to get the peer address # # This is from the netpipes package PEER="‘getpeername | cut -d ’ ’ -f 1‘"
120 read_request
exit 0 ¦ ¥
Now run telnet localhost 80, as in Section 26.2. If that works and your log files are being properly appended (use tail -f . . . ), you can try to connect to http://localhost/ with a web browser like Netscape.
Notice also that the command getsockname (which tells you which of your own IP addresses the remote client connected to) could allow the script to serve pages from a different directory for each IP address. This is virtual domains in a nutshell. &Groovy, baby, I’m in a giant nutshell.... how do I get out?-
392 36. httpd — Apache Web Server 36.2. Installing and Configuring Apache
36.2 Installing and Configuring Apache
Because all distributions package Apache in a different way, here I assume Apache to have been installed from its source tree, rather than from a .deb or .rpm package. You can refer to Section 24.1 on how to install Apache from its source .tar.gz file like any other GNU package. (You can even install it under Win- dows, Windows NT, or OS/2.) The source tree is, of course, available from The Apache Home Page http://www.apache.org. Here I assume you have installed it in -- prefix=/opt/apache/. In the process, Apache will have dumped a huge reference manual into /opt/apache/htdocs/manual/.
36.2.1 Sample httpd.conf
Apache has several legacy configuration files: access.conf and srm.conf are two of them. These files are now deprecated and should be left empty. A single configura- tion file /opt/apache/conf/httpd.conf may contain at minimum: § ¤ ServerType standalone ServerRoot "/opt/apache" PidFile /opt/apache/logs/httpd.pid ScoreBoardFile /opt/apache/logs/httpd.scoreboard 5 Port 80 User nobody Group nobody HostnameLookups Off ServerAdmin [email protected] 10 UseCanonicalName On ServerSignature On DefaultType text/plain ErrorLog /opt/apache/logs/error_log LogLevel warn 15 LogFormat "%h %l %u %t \"%r\" %>s %b" common CustomLog /opt/apache/logs/access_log common DocumentRoot "/opt/apache/htdocs" DirectoryIndex index.html AccessFileName .htaccess 20
393 36.2. Installing and Configuring Apache 36. httpd — Apache Web Server
Order allow,deny Allow from all 35
With the config file ready, you can move the index.html file above to /opt/apache/htdocs/. You will notice the complete Apache manual and a demo page already installed there; you can move them to another directory for the time be- ing. Now run § ¤ /opt/apache/bin/httpd -X ¦ ¥ and then point your web browser to http://localhost/ as before.
36.2.2 Common directives
Here is a description of the options. Each option is called a directive in Apache terminology. A complete list of basic directives is in the file /opt/apache/htdocs/manual/mod/core.html.
ServerType As discussed in Section 29.2, some services can run standalone or from inetd (or xinetd). This directive can be exactly standalone or inetd. If you choose inetd, you will need to add an appropriate line into your inetd configuration, although a web server should almost certainly choose standalone mode.
ServerRoot This is the directory superstructure &See page 137.- under which Apache is installed. It will always be the same as the value passed to --prefix=. PidFile Many system services store the process ID in a file for shutdown and moni- toring purposes. On most distributions, the file is /var/run/httpd.pid. ScoreBoardFile This option is used for communication between Apache parent and child processes on some non-UNIX systems. Port This is the TCP port for standalone servers to listen on. User, Group This option is important for security. It forces httpd to user nobody privileges. If the web server is ever hacked, the attack will not be able to gain more than the privileges of the nobody user.
394 36. httpd — Apache Web Server 36.2. Installing and Configuring Apache
HostnameLookups To force a reverse DNS lookup on every connecting host, set this directive to on. To force a forward lookup on every reverse lookup, set this to double. This option is for logging purposes since access control does a reverse and forward reverse lookup anyway if required. It should certainly be off if you want to reduce latency. ServerAdmin Error messages include this email address. UseCanonicalName If Apache has to return a URL for any reason, it will normally return the full name of the server. Setting to off uses the very host name sent by the client. ServerSignature Add the server name to HTML error messages. DefaultType All files returned to the client have a type field specifying how the file should be displayed. If Apache cannot deduce the type, it assumes the MIME Type to be text/plain. See Section 12.6.2 for a discussion of MIME types. ErrorLog Where errors get logged, usually /var/log/httpd/error log LogLevel How much info to log. LogFormat Define a new log format. Here we defined a log format and call it com- mon. Multiple lines are allowed. Lots of interesting information can actually be logged: See /opt/apache/htdocs/manual/mod/mod log config.html for a full description. CustomLog The log file name and its (previously defined) format. DocumentRoot This directive specifies the top-level directory that client connec- tions will see. The string /opt/apache/htdocs/ is prepended to any file lookup, and hence a URL http://localhost/manual/index.html.en will return the file /opt/apache/htdocs/manual/index.html.en. DirectoryIndex This directive gives the default file to try serve for URLs that con- tain only a directory name. If a file index.html does not exist under that direc- tory, an index of the directory is sent to the client. Other common configurations use index.htm or default.html. AccessFileName Before serving a file to a client, Apache reads additional directives from a file .htaccess in the same directory as the requested file. If a parent directory contains a .htaccess instead, this one will take priority. The .htac- cess file contains directives that limit access to the directory, as discussed below.
The above is merely the general configuration of Apache. To actually serve pages, you need to define directories, each with a particular purpose, containing particular HTML or graphic files. The Apache configuration file is very much like an HTML document. Sections are started with
395 36.2. Installing and Configuring Apache 36. httpd — Apache Web Server
The most common directive of this sort is
Options The Options directive controls which server features are available in a par- ticular directory. There is also the syntax +option or -option to include the options of the parent directory, for example, Options +FollowSymLinks -Indexes.
FollowSymLinks The server will follow any symbolic links beneath the direc- tory. Be careful about what symbolic links you have beneath directories with FollowSymLinks. You can, for example, give everyone access to the root directory by having a link ../../../ under htdocs—not what you want. ExecCGI Execution of CGI scripts is permitted. Includes Server-side includes are permitted (more on this later). IncludesNOEXEC Server-side includes are permitted, but the #exec command and #include of CGI scripts are disabled. Indexes If a client asks for a directory by name and no index.html file (or whatever DirectoryIndex file you specified) is present, then a pretty list- ing of the contents of that directory is created and returned. For security you may want to turn this option off. MultiViews Content-negotiated MultiViews are allowed (more on this later). SymLinksIfOwnerMatch The server will only follow symbolic links for which the target file or directory is owned by the same user ID as the link (more on this later). All All options except for MultiViews. This is the default setting.
Deny Hosts that are not allowed to connect. You can specify a host name or IP address, for example, as: § ¤ Deny from 10.1.2.3 Deny from 192.168.5.0/24 Deny from cranzgot.co.za ¦ ¥
396 36. httpd — Apache Web Server 36.2. Installing and Configuring Apache
which will deny access to 10.1.2.3, all hosts beginning with 192.168.5., and all hosts ending in .cranzgot.co.za, including the host cranzgot.co.za.
Allow Hosts that are allowed to connect. This directive uses the same syntax as Deny.
Order If order is Deny,Allow, then the Deny directives are checked first and any client that does not match a Deny directive or does match an Allow directive will be allowed access to the server. If order is Allow,Deny, then the Allow directives are checked first and any client that does not match an Allow directive or does match a Deny directive will be denied access to the server.
AllowOverride In addition to the directives specified here, additional directives will be read from the file specified by AccessFileName, usually called .htac- cess. This file would usually exist alongside your .html files or otherwise in a parent directory. If the file exists, its contents are read into the cur- rent
You can see that we give very restrictive Options to the root directory, as well as very restrictive access. The only server feature we allow is FollowSymLinks, then we Deny any access, and then we remove the possibility that a .htaccess file could override our restrictions. The
We are now finally ready to add actual web page directories. These take a less restrictive set of access controls: § ¤
397 36.2. Installing and Configuring Apache 36. httpd — Apache Web Server
36.2.3 User HTML directories
Our users may require that Apache know about their private web page directories ˜/www/. This is easy to support with the special UserDir directive: § ¤
36.2.4 Aliasing
Sometimes, HTML documents will want to refer to a file or graphic by using a simple prefix, rather than a long directory name. Other times, you want two different refer- ences to source the same file. The Alias directive creates virtual links between direc- tories. For example, adding the following line, means that a URL /icons/bomb.gif will serve the file /opt/apache/icons/bomb.gif: § ¤ Alias /icons/ "/opt/apache/icons/" ¦ ¥ We do, of course, need to tell Apache about this directory: § ¤
398 36. httpd — Apache Web Server 36.2. Installing and Configuring Apache
5 Allow from all ¦ ¥
36.2.5 Fancy indexes
You will find the directory lists generated by the preceding configuration rather bland. The directive § ¤ IndexOptions FancyIndexing ¦ ¥ causes nice descriptive icons to be printed to the left of the file name. What icons match what file types is a trick issue. You can start with: § ¤ AddIconByEncoding (CMP,/icons/compressed.gif) x-compress x-gzip AddIconByType (TXT,/icons/text.gif) text/* AddIconByType (IMG,/icons/image2.gif) image/* AddIconByType (SND,/icons/sound2.gif) audio/* 5 AddIconByType (VID,/icons/movie.gif) video/* AddIcon /icons/compressed.gif .Z .z .tgz .gz .zip AddIcon /icons/a.gif .ps .eps AddIcon /icons/layout.gif .html .shtml .htm ¦ ¥ This requires the Alias directive above to be present. The default Apache configura- tion contains a far more extensive map of file types.
36.2.6 Encoding and language negotiation
You can get Apache to serve gzipped files with this: § ¤ AddEncoding x-compress Z AddEncoding x-gzip gz ¦ ¥ Now if a client requests a file index.html, but only a file index.html.gz exists, Apache decompresses it on-the-fly. Note that you must have the MultiViews options enabled. The next options cause Apache to serve index.html.language-code when in- dex.html is requested, filling in the preferred language code sent by the web browser. Adding these directives causes your Apache manual to display correctly and will prop- erly show documents that have non-English translations. Here also, the MultiViews must be present. § ¤ AddLanguage en .en
399 36.2. Installing and Configuring Apache 36. httpd — Apache Web Server
AddLanguage da .dk AddLanguage nl .nl AddLanguage et .ee 5 AddLanguage fr .fr AddLanguage de .de AddLanguage el .el AddLanguage ja .ja AddLanguage ru .ru 10 LanguagePriority en da nl et fr de el ja ru ¦ ¥ The LanguagePriority directive indicates the preferred language if the browser did not specify any. Some files might contain a .koi8-r extension, indicating a Russian character set encoding for this file. Many languages have such custom character sets. Russian files are named webpage.html.ru.koi8-r. Apache must tell the web browser about the encoding type, based on the extension. Here are directives for Japanese, Russian, and UTF-8 &UTF-8 is a Unicode character set encoding useful for any language.-, as follows: § ¤ AddCharset ISO-2022-JP .jis AddCharset KOI8-R .koi8-r AddCharset UTF-8 .utf8 ¦ ¥
Once again, the default Apache configuration contains a far more extensive map of languages and character sets.
36.2.7 Server-side includes — SSI
Apache actually has a built-in programming language that interprets .shtml files as scripts. The output of such a script is returned to the client. Most of a typical .shtml file will be ordinary HTML, which will be served unmodified. However, lines like § ¤ ¦ ¥ will be interpreted, and their output included into the HTML—hence the name server- side includes. Server-side includes are ideal for HTML pages that contain mostly static HTML with small bits of dynamic content. To demonstrate, add the following to your httpd.conf: § ¤ AddType text/html .shtml AddHandler server-parsed .shtml
400 36. httpd — Apache Web Server 36.2. Installing and Configuring Apache
Allow from all ¦ ¥ Create a directory /opt/apache/htdocs/ssi with the index file index.shtml: § ¤ The date today is .
Here is a directory listing:
5¦ ¥ and then a file footer.html containing anything you like. It is obvious how useful this procedure is for creating many documents with the same banner by means of a #include statement. If you are wondering what other variables you can print besides DATE LOCAL, try the following: § ¤
5 ¦ ¥
You can also goto http://localhost/manual/howto/ssi.html to see some other examples.
36.2.8 CGI — Common Gateway Interface
(I have actually never managed to figure out why CGI is called CGI.) CGI is where a URL points to a script. What comes up in your browser is the output of the script (were it to be executed) instead of the contents of the script itself. To try this, create a file /opt/apache/htdocs/test.cgi: § ¤ #!/bin/sh
echo ’Content-type: text/html’ echo 5 echo ’’ echo ’
’ echo ’’ echo ’Please visit’
401 36.2. Installing and Configuring Apache 36. httpd — Apache Web Server
echo ’ ’ echo ’ The Rute Home Page’ echo ’ ’ 15 echo ’for more info.
’ echo ’ ’ echo ’’ ¦ ¥Make this script executable with chmod a+x test.cgi and test the output by running it on the command-line. Add the line § ¤ AddHandler cgi-script .cgi ¦ ¥ to your httpd.conf file. Next, modify your Options for the directory /opt/apache/htdocs to include ExecCGI, like this: § ¤
After restarting Apache you should be able to visit the URL http://localhost/test.cgi. If you run into problems, don’t forget to run tail /opt/apache/logs/error log to get a full report. To get a full list of environment variables available to your CGI program, try the following script: § ¤ #!/bin/sh
echo ’Content-type: text/html’ echo 5 echo ’’ echo ’
’ set echo ’’ echo ’’ ¦ ¥ The script will show ordinary bash environment variables as well as more interesting variables like QUERY STRING: Change your script to § ¤ #!/bin/sh
echo ’Content-type: text/html’ echo
402 36. httpd — Apache Web Server 36.2. Installing and Configuring Apache
5 echo ’’ echo ’
’ echo $QUERY_STRING echo ’’ echo ’’ ¦ ¥ and then go to the URL http://localhost/test/test.cgi?xxx=2&yyy=3. It is easy to see how variables can be passed to the shell script. The preceding example is not very interesting. However, it gets useful when scripts have complex logic or can access information that Apache can’t access on its own. In Chapter 38 we see how to deploy an SQL database. When you have covered SQL, you can come back here and replace your CGI script with, § ¤ #!/bin/sh
echo ’Content-type: text/html’ echo
5 psql -d template1 -H -c "SELECT * FROM pg_tables;" ¦ ¥ This script will dump the table list of the template1 database if it exists. Apache will have to run as a user that can access this database, which means changing User no- body to User postgres. &Note that for security you should really limit who can connect to the postgres database. See Section 38.4.-
36.2.9 Forms and CGI
To create a functional form, use the HTTP
25 ¦ ¥ which looks like:Note how this form calls our existing test.cgi script. Here is a script that adds the entered data to a postgres SQL table: § ¤ #!/bin/sh
echo ’Content-type: text/html’ echo
5 opts=‘echo "$QUERY_STRING" | \ sed -e ’s/[ˆA-Za-z0-9 %&+,.\/:=@_˜-]//g’ -e ’s/&/ /g’ -e q‘
for opt in $opts ; do 10 case $opt in name=*) name=${opt/name=/} ;; email=*) 15 email=${opt/email=/} ;; tel=*) tel=${opt/tel=/} ;; 20 esac
404 36. httpd — Apache Web Server 36.2. Installing and Configuring Apache
done
if psql -d template1 -H -c "\ INSERT INTO people (name, email, tel) \ 25 VALUES (’$name’, ’$email’, ’$tel’)" 2>&1 | grep -q ’ˆINSERT ’ ; then echo "Your details \"$name\", \"$email\" and \"$tel\"
" echo "have been succesfully recorded." else echo "Database error, please contact our webmaster." 30 fi
exit 0 ¦ ¥
Note how the first lines of script remove all unwanted characters from QUERY STRING. Such processing is imperative for security because shell scripts can easily execute commands should characters like $ and ‘ be present in a string. To use the alternative “POST” method, change your FORM tag to § ¤