CERN Accelerating science

Introduction

This article is intended for people publishing documents on Apache Web servers. It explains the use of some of the tools allowing dynamic functions in Web documents and access control on Web pages/sites.

In order to provide this service, the Apache server looks for a file named .htaccess in each directory along the path to a Web document. This file contains special instructions telling the server what rules apply in that directory and all the directories under it. In general, top level directories are left public and have no .htaccess file, while some lower directories might be restricted. It is also possible to specify new .htaccess files for lower directories and thus overrule the existing values specified by higher level .htaccess files.

1. Server Side Includes.

"Server Side Includes" (SSI) is an easy way to add dynamic features to HTML files, such as the current date or the document last modification date, without using a CGI-script. SSI lets you embed a number of special 'commands' into the HTML itself. When the server reads an SSI document it looks for these special commands and performs the necessary action. For example, if an HTML document contains the SSI command <!--#echo var="REMOTE_ADDR" --> the server will replace this command by the ip-address of the computer from which the page is viewed, 137.138.36.205 for instance.

1.1. Telling Apache to Use SSI

By default, the server does not look for SSI commands in the HTML files. To use SSI you need to tell Apache which documents contain the SSI commands. The easiest way to do this is to add the following lines to a local .htaccess file.

XBitHack on
Options Includes
AddHandler server-parsed.html
AddType text/html html

The Options directive tells the server to allow SSI. The AddHandler directive tells Apache to treat every .html file as one that can include SSI commands. The AddType directive makes the resulting document be given the MIME type of text/html so that the browser displays it properly. The XBitHack directive controls the parsing of ordinary html documents. This directive only affects files associated with the MIME type text/html. Of course, you can define other file extensions or several file extensions as files containing SSI commands with lines like:

AddHandler server-parsed .html .htm .shtml .shtm
AddType text/html html htm shtml shtm

1.2. SSI Commands.

Here are some basic SSI commands that are easy to use:

1.- This document was last modified on

<!--#config timefmt="%B %e, %Y" -->
<!--#echo var="LAST_MODIFIED" -->

2.- You are connecting from

<!--#echo var="REMOTE_HOST" -->

3.- With the IP address of

<!--#echo var="REMOTE_ADDR" -->

2. Making a directory browsable

Syntax: DirectoryIndex local-url local-url ...

The DirectoryIndex directive in the .htaccess file sets the list of files to look for when the client requests an index of the directory by specifying a "/" at the end of the directory name, e.g. http://wwwinfo.cern.ch/~somebody/

By default, the server will look typically for a Welcome.html file or welcome.html or index.html if the DirectoryIndex directive is not specified. For instance, by specifying:

DirectoryIndex comeon.html

you tell the server to look only for file comeon.html in the current directory and display it if found. The DirectoryIndex directive overrides the settings made by the server administrator, so now the server does not look for files index.html or welcome.html and does not display them even if they are in the directory. You will have to specify them in the directive if you want them to be used.

With the Indexes directive on the Options line, the server will show a formatted listing of the directory requested in the URL, provided that the directory does not contain any of the files specified by the DirectoryIndex directive.

With the FollowSymLinks directive the server will follow symbolic links in this directory.

So by now the .htaccess file could look something like:

Options Indexes FollowSymLinks
AddHandler server-parsed .html .htm .shtml .shtm
AddType text/html html htm shtml shtm
DirectoryIndex comeon.html welcome.html

3. How to protect your data

In Apache there are two approaches of access restriction to documents:

• by the hostname of the browser being used.
• by asking for a username and password.

This second way is called user authentication (we expand further on this below).

3.1. Restricting by hostname

To restrict access by the hostname of the browser being used, you need to add to the .htaccess file the following lines telling the server who to let through and who not:

order deny,allow
deny from all
allow from .cern.ch

Now only people connecting from CERN can access the pages in the directory. If you wanted to allow everybody except one specific machine from CERN to see your pages you could write:

order allow,deny
deny from pcuco04.cern.ch
allow from all

The order directive defines the order in which deny and allow directives are evaluated.

3.2. Restricting by username and password

Setting up user authentication requires two steps:

• Firstly, you create a file containing the usernames and passwords.
• Secondly, you tell the server what data is to be protected and which users are allowed (after entering a valid password) to access them.

david:FD2Dk.zMGUPD.
isabel:XfViT467MJO4g
pepe:JYPBeq9c06l.U
montse:5RWASJ5urWri.
sacra:fDASEgc53SghH

Usually this file is created by the system administrator, but it is possible to do it yourself. You will need to create this file in one of your local directories, e.g. ~/www/. In this file the passwords are encrypted by a program called htpasswd. The Web server administrator can explain to you how/where this program is installed.

In Apache the .htpasswd and .htgroups files (described below) do not have to be globally readable, unlike standard UNIX Web servers, so you can protect them such that nobody can see their contents. You can use a command like:

chmod 700 .htpasswd .htgroups

Once you have your .htpasswd file, you have to tell the server who can see the pages in the current directory. To do this enter the following lines in your .htaccess file:

AuthName <symbolic_name>
AuthType Basic
AuthUserFile <path to your .htpasswd file>

require valid-user

The AuthType directive tells the server what protocol is to be used for authentication. At the moment, Basic is the only method available. However a new method, Digest, is about to be standardised, and once browsers start to implement it, digest authentication will provide more security than the basic authentication.

AuthUserFile tells the server the location of the .htpasswd file (you should specify the full path of this file).

require tells the server which usernames from the .htpasswd file are valid for particular access methods. The argument valid-user tells the server that any username in the .htpasswd file can be used. However, it could be configured to allow only certain users in that file, e.g.:

require user pepe sacra

3.2.1. Using Groups

If you want to allow only selected people in the .htpasswd file into a particular area, you should use groups. The group file should be called .htgroups and it will be located in the same directory as the .htpasswd file. The same person can belong to more than one group. All the usernames in the .htgroups file must be present in the .htpasswd file.

Example of a .htgroups file:

admin:isabel david
team:david pepe montse

To restrict access to just users in the admin group, you would use in .htaccess the directive:

require group admin

You will need to add the AuthGroupFile directive after the AuthUserFile directive to specify the location of the .htgroups file.

3.2.2. Examples

Here are some examples of the lines you could write in the .htaccess file to use user authentication:

1.- Directory accessible for just two users in the .htaccess file.

AuthName  Example1
AuthType    Basic
AuthUserFile   /afs/cern.ch/user/y/your_dir/www/.htpasswd
require user  caro fuen

2.- Directory accessible for people belonging to group admin in the .htgroups file.

AuthName Example2
AuthType Basic
AuthUserFile     /afs/cern.ch/user/y/your_home/www/.htpasswd
AuthGroupFile  /afs/cern.ch/user/y/your_home/www/.htgroups
require group admin

3.- Directory accessible for people logging from CERN machines or who have a valid username and password

AuthName  Example3
AuthType  Basic
Satisfy any

AuthUserFile   /afs/cern.ch/user/y/your_home/www/.htpasswd
require valid-user

You can use the Satisfy all directive if you want the user to satisfy both location and password requirements.

3.2.3. Using <Files>

Syntax: <Files filename> ... </Files>

If you want to limit access to specific files within a directory, rather than an entire directory, you will use the restriction methods described above within <Files> and </Files> directives. Example:

<Files example.html>
order deny,allow
deny from all
allow from .cern.ch
</Files>

with example.html in the same directory as the .htaccess file. In each <Files> to </Files> section, you can only specify one filename to control access. However, if you want to control access to multiple files, you can use wildcards (*). If, for example, you have three files you want to be accessible only by CERN users, called course1.html, course2.html, and course3.html, then the first line of your .htaccess file would be:

<Files course*.html>

You can also use multiple <Files> to </Files> sections within your .htaccess file.

4. Using Redirect

Syntax: Redirect [ status ] url-path url

Sometimes you can be forced to move files to other directories or other servers, because of disk space limitations for example. With the Redirect directive it is possible to map an old URL into a new one. The new URL is returned to the client which attempts to fetch it again with the new address. With this you do not have to tell everybody that some of your pages have moved; people will automatically be redirected to the new locations.

By adding the following line in the .htaccess file you will redirect all the requests for directory old_dir to the new_dir of the new server.

Redirect  /~your_home/old_dir  http://www.newserver.com/~your_home/new_dir

Of course, you can redirect these requests to a directory on the same server, but you always have to specify a complete URL for this directory. The Url-path must be an absolute path, not just a relative path from the directory the .htaccess file is in.

You can also redirect single pages, rather than whole directories. With the following command, somebody trying to access the page example.html on your Web directory will get the main page from Altavista:

Redirect /~YOUR_HOME/example.html http://www.altavista.com

These features can be useful in the case that you have big pictures on your pages and you move them somewhere else: You do not have to rewrite the html code telling the new locations of these pictures because they will automatically be taken from their new location.

If no status argument is given, the client will be told that the redirect is "temporary" (HTTP status 302). The status argument can be used to return other HTTP status codes:

permanent

References:

• A Server Side Includes (SSI).
• A table of the SSI Time Formats and Common Errors.
• Examples on how to use SSI commands
• Instructions for all possible SSI commands.
• How to protect your data yourself
• Notes on .htaccess with examples