mod_access_referer Apache module
Author: Arturo Tena

# mod_access_referer Module for the Apache HTTP Server

Version 1.0.1

This is an module for the Apache HTTP Server that provides access control based on "Referer" HTTP header content.

- allow_referer
- deny_referer
- order_referer
- default_access_referer
- Motivation
- Miscellaneous

## allow_referer directive

Syntax: allow_referer from host host ...
Context: directory, location, .htaccess
Override: Never
Module: mod_access_referer

The allow_referer directive affects which hosts can refer and access a given directory. host is one of the following:

`all`
  All referer hosts are allowed refer and access.
A (partial) domain-name
  Referer hosts whose names match, or end in, this string are allowed refer and access.
A full IP address
  An IP address of a referer host allowed refer and access.
A partial IP address
  The first 1 to 3 bytes of an IP address, for subnet restriction.
A network/netmask pair
  A network a.b.c.d, and a netmask w.x.y.z. For more fine-grained subnet restriction. (i.e., 10.1.0.0/255.255.0.0)
A network/nnn CIDR specification
  Similar to the previous case, except the netmask consists of nnn high-order 1 bits. (i.e., 10.1.0.0/16 is the same as 10.1.0.0/255.255.0.0)

Example:

> `allow_referer from .ncsa.uiuc.edu`

In this case all hosts in the specified domain are allowed access.

Note that this compares whole components; `bar.edu` would not match `foobar.edu`.

See also deny_referer, order_referer and default_access_referer.

## deny_referer directive

Syntax: deny_referer from host host ...
Context: directory, location, .htaccess
Override: Never
Module: mod_access_referer

The deny_referer directive affects which referer hosts can not refer and access a given directory. host is one of the following:

`all`
  All referer hosts are denied refer and access.
A (partial) domain-name
  Referer hosts whose names match, or end in, this string are denied refer and access.
A full IP address
  An IP address of a referer host denied refer and access.
A partial IP address
  The first 1 to 3 bytes of an IP address, for subnet restriction.
A network/netmask pair
  A network a.b.c.d, and a netmask w.x.y.z. For more fine-grained subnet restriction. (i.e., 10.1.0.0/255.255.0.0)
A network/nnn CIDR specification
  Similar to the previous case, except the netmask consists of nnn high-order 1 bits. (i.e., 10.1.0.0/16 is the same as 10.1.0.0/255.255.0.0)

Example:

> `deny_referer from 16`

In this case all referer hosts in the specified network are denied referer and access.

Note that this compares whole components; `bar.edu` would not match `foobar.edu`.

See also allow_referer, order_referer and default_access_referer.

## order_referer directive

Syntax: order_referer ordering
Default: `order_referer deny_referer,allow_referer`
Context: directory, location, .htaccess
Override: Never
Module: mod_access_referer

The order_referer directive controls the order in which allow_referer and deny_referer directives are evaluated. ordering is one of the following:

deny_referer,allow_referer
  The deny_referer directives are evaluated before the allow_referer directives. (The initial state is OK.)
allow_referer,deny_referer
  The allow_referer directives are evaluated before the deny_referer directives. (The initial state is FORBIDDEN.)
mutual-failure
  Only those hosts which appear on the allow_referer list and do not appear on the deny_referer list are granted referer and access. (The initial state is irrelevant.)

Example:

> `order_referer allow_referer,deny_referer`
> `deny_referer from all`
> `allow_referer from .ncsa.uiuc.edu`

In this case hosts in the `ncsa.uiuc.edu` domain are allowed referer and access; all other hosts are denied referer and access.

See also allow_referer, deny_referer and default_access_referer.

## default_access_referer directive

Syntax: default_access_referer access
Default: `default_access_referer allow_referer`
Context: directory, location, .htaccess
Override: Never
Module: mod_access_referer

The default_access_referer directive affects if referer host can referer and access a given directory if the "Referer" HTTP header is not sent by the browser. access is one of the following:

allow_referer
  All referer hosts are allowed referer and access if the browser don't send the "Referer" HTTP header.
deny_referer
  All referer hosts are denied refer and access if the browser don't send the "Referer" HTTP header.

Example:

> `default_access_referer allow_referer`

In this case if the browser don't send the "Referer" HTTP header, it will be allowed access.

See also allow_referer, deny_referer and order_referer.

## Motivation

There are many organizations that publish valuable files (pictures, charts, and other documents) in their Web sites. Those organizations want to make public those files, but at the same time they want the people having visiting their Web sites in order to get those files (example, in order to get revenue from sell banners which are shown at the Web site).

But, there are situations where the files are linked from other Web sites, other than the organization owns. In such situations, the organization is loosing twice: one because the people don't visit the organization's Web site to get the files, and another because the organization still pay the necessary bandwidth to get the files.

Most browsers today send the "Referer" HTTP header in each request that comes from another Web page. This can be used to track from where the resources are linked, but it can be used to allow or deny the access to such resources if the "Referer" is not a page from the organization's Web site.

mod_access_referer is an Apache module that understand the "Referer" HTTP header, and grant or deny access based on the Web page that refered the file.

The "Referer" HTTP header is sent by the browser to the server, and it contains the URL of the resource from where the URL of the asked resource was obtained. The document "Hypertext Transfer Protocol -- HTTP/1.1" RFC 2616 gives the following explanation:

> "The Referer[sic] request-header field allows the client to specify, for the server's benefit, the address (URI) of the resource from which the Request-URI was obtained (the "referrer", although the header field is misspelled.) The Referer request-header allows a server to generate lists of back-links to resources for interest, logging, optimized caching, etc. It also allows obsolete or mistyped links to be traced for maintenance. The Referer field MUST NOT be sent if the Request-URI was obtained from a source that does not have its own URI, such as input from the user keyboard."

## Miscellaneous

Copyright (c) 1999, 2000 The Apache Group. All rights reserved.

You can download the source code of this module at http://accessreferer.sourceforge.net/.

Original author: Roberto Arturo Tena Sánchez <arturo__at__users.sourceforge.net>

This module was been developed with help from Cosource.com.