View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
George Sanderson > OpenIndex-1.05 > Apache::OpenIndex



Annotate this POD

View/Report Bugs
Module Version: 1.04b   Source  


Apache::OpenIndex - Perl Open Index manager for a Apache Web server


  PerlModule Apache::Icon
  PerlModule Apache::OpenIndex
  (PerlModule Apache::Language) optional
  (PerlModule Image::Magick)    optional


OpenIndex provides a file manager for a web sites through a web browser. It is a extensive rewrite of the module which in turn was a remake of the autoindex Apache module. OpenIndex can provide the same functionality as and can be used to both navigate and manage the web site.

OpenIndex has dropped the mod_dir support provided by AutoIndex.

In order to activate the file manager functionality, two things have to happen. First, the proper http.conf directives need to be placed into a <Location area> section. Second, there has to be a directory stub (.XOI) created off of the directory where the file manager is to be provided.

Within the ROOT directory stub (.XOI), a MARK sub-directory (.XOI/.MARK) can also be provided to present a MARK directory tree by the file manager. The MARK (.XOI/.MARK) directory provides a physical directory where files can be managed, unzipped, moved, copied, deleted, and renamed. New directories can be created with the mkdir command. The MARK directory can be mapped to any path location on the Apache server or to any site path location. To activate the MARK directory access the "mark" directive needs to be set to '1'. The ROOT (.XOI) directory is actually a fake path of the site's root directory. For example to access "" the following URL would be required:


This would in turn would display the file manager for bob. To Bob, the ROOT directory appears to be his actual web root directory.

If the above description does not make sense, just follow the examples provided, and perhaps it will become clearer once you see some results.

Since a URL fake path (.XOI) is provided, authentication and authorization can be used to only allow authorized users to have access to the OpenIndex module.

In short, you will no longer need to use ftp to upload and manage the web site files. Since OpenIndex is web based, you can use all of your other Apache functionality, such as SSL, proxies, and etc.

The best procedure to get OpenIndex loaded and working is to first have the Apache mod_perl and autoindex modules loaded and working properly. Then remove the httpd.conf "AddModule autoindex" directive and add the Apache::Icon and Apache::OpenIndex module directives.


Loading the Modules

The following describes what httpd.conf directives you need in your httpd.conf file to load OpenIndex and it's companion modules.

First or all you must have mod_perl loaded, with the following:

AddModule mod_perl.c

You will also need to load the following mod_perl modules, with:

  PerlModule Apache::Icon
  PerlModule Apache::OpenIndex

in your httpd.conf file or with:

   use Apache::Icon();
   use Apache::OpenIndex();

in your file.

Configuration Guidelines

It is best to put the OpenIndex directives is in a <Location area> section of your httpd.conf file, because it is the highest priority Apache httpd.conf section. This way, other directives will not get in the way of (ahead of) OpenIndex during the Apache request processing. Apache 1.3.x the directive section priorities are (in increasing order):


Here is an example of a <Location area> directive:

    <LocationMatch /.*/\.XOI>
        SetHandler perl-script
        PerlHandler Apache::OpenIndex

Notice that a regular expression Location form was used. This will provide a file manager for each 1-level deep sub-directory of the site's document root which have a .XOI stub directory in them. For example:


If a browser in turn accesses:


The OpenIndex file manager would be activated for "/friends/bob".

Even though the .XOI directory is a fake reference for the real directory tree, it must exist in order to activate the file manager. If a ".XOI/.MARK" directory is also present, and the "mark" directive is set to '1', access to any location on the Apache server can be managed.

You will probably want to provide authentication and authorization for the .XOI fake location. For example, I have used Apache::AuthenDBI and Apache::AuthzDBI with the following additions to the same <Location> as above:

 PerlAuthenHandler Apache::AuthenDBI
 PerlAuthzHandler  Apache::AuthzDBI
 AuthName DBI
 AuthType Basic
 PerlSetVar Auth_DBI_data_source  dbi:Pg:dbname=webdb
 PerlSetVar Auth_DBI_username     webuser
 PerlSetVar Auth_DBI_password     webpass
 PerlSetVar Auth_DBI_pwd_table    users
 PerlSetVar Auth_DBI_uid_field    username
 PerlSetVar Auth_DBI_grp_field    GID
 PerlSetVar Auth_DBI_pwd_field    password
 PerlSetVar Auth_DBI_encrypted    on
 require group webgroup friends propellers

If you only want to provide the AutoIndex functionality, just place the following into either a <Directory area>, or <Location area> directive and don't bother to create the .XOI directory.

 SetHandler perl-script
 PerlHandler Apache::OpenIndex

Mod_perl does not provide configuration merging for Apache virtual hosts. Therefore, you have to maintain a complete set of OpenIndex directives for each virtual host, if any of the virtual host configurations are different.

File Permissions

When using OpenIndex as a file manager, understanding and implementing the file permissions is the hardest concept. First, you need to have a good understanding of your operating system's (OS) file permissions.

OpenIndex can allow groups of users to share the same web server file space (tree), such that individuals can be prevented from changing each others files and directories. An "admin" group can also be specified, which allows certain users to be able to modify all the files and directories within the tree, as well as, assign GID access to the files and directories.

File permissions are controlled by a group ID (GID) provided by an authorization module for the user. It is assigned to the files and directories that that user creates.

An Apache environment variable must be set prior to each OpenIndex request. This environment variable would normally be set by an authorization module.

For example, the Apache::AuthzDBI module (presented above) can provide an environment variable "REMOTE_GROUP" which contains the group ID of the authorized user. The following OpenIndex directive tells it which environment variable contains the user's GID for the request:

    OpenIndexOptions GIDEnv=REMOTE_GROUP

For example, if the authorization module sets the environment variable:


OpenIndex would set the GID for that user to 1000. If the GID is valid (for Apache and it's OS), all files and directories created by that user will have their GID set to 1000.

HINT: If you set the "OpenIndexOptions Debug 1" directive, the environment variables will be listed along with other debugging information. You can then spot your GID environment variable set by your authorization module in order to verify it's existence and OpenIndex operation.

An admin directive can also be specified which enables a user with the specified admin GID to access and control all files and directories within the current file manager directory (.XOI) tree.

In summary, if the following directives are provided:

  OpenIndexOptions GIDEnv=REMOTE_GROUP
  OpenIndexOptions Admin=1000

The GIDEnv directive tells OpenIndex which environment variable contains the GID (REMOTE_GROUP in this example). [This variable would have been set by an authorization module.] If the GID for the user happens to be 1000, then that user will have "admin" privileges and it's commands (SetGID).

The operating system (OS) rules still apply to all of the GID operations. For example (OS=UNIX), if Apache's program ID (PID) is 100 and a file is owned by user 200, Apache can not change the GID of file unless the Apache process is also a member of the GID 200 group.

If a "group name" (instead of a number) is provided, the GID name is looked-up in the /etc/group file in order to obtain the numeric GID. This is very UNIX like and my not work for other operating systems.

HINT: Any environment variable can be used to contain the GID. Therefore, you can trick the authorization module into coughing up a GID by using the REMOTE_USER (user) environment variable and then simply create a group with the same name. Don't forget to make the Apache's process user ID (PUID) a member of the group (in /etc/group).

AutoIndex Functionality

When a .XOI directory is not present in the URL, OpenIndex will function like AutoIndex. Note that the .XOI directory name can be changed with a directive. This is explain later on in the text.


The display options (directives) are a composite of autoindex, AutoIndex, and OpenIndex's own module directives.

The original module directives are maintained by OpenIndex, so that any existing directives that you may have, can be used to maintain the status quo.

autoindex DIRECTIVES

Apache normally comes with mod_autoindex C module. A number of it's httpd.conf directives are provided when Apache is installed.

Documentation for autoindex can be found at:

An incomplete (no Alt directives) and a very brief description of the autoindex (used by Apache::Icon) directives is provided below.

These directives are processed by which provides icons to Apache::AutoIndex and Apache::OpenIndex.




Generation of thumbnails is possible. This means that listing a directory that contains images can be listed with little reduced thumbnails beside each image name instead of the standard 'image' icon.

To enable this you simply need to preload Image::Macick in Apache. The IndexOption option Thumbnails controls thumbnails generation for specific directories like any other IndexOption directive.


The way thumbnails are generated/produced can be configured in many ways. A general overview of the procedure follows.

For each directory containing pictures, there will be a .thumbnails directory created in it that will hold the thumbnails. Each time the directory is accessed, and if thumbnail generation is active, small thumbnails will be produced, shown beside each image name, instead of the normal , generic, image icon.

That can be done in 2 ways. In the case the image is pretty small, no actual thumbnail will be created. Instead the image will resize the HEIGHT and WIDTH attributes of the IMG tag.

If the image is big enough, Image::Magick will resize it and save (cache) it in the .thumbnails directory for the next requests.

Changing configuration options will correctly refresh the cached thumbnails. Also, if the original image is modified, the thumbnail will be updated accordingly. Still, the browser might screw things up if it preserves the cached images.



The thumbnail support needs to be tested. It was provide with Apache:: AutoIndex, but I have not tested it yet.

Some minor changes to the thumbnails options will still have the thumbnails regenerated. This should be avoided by checking the attributes of the already existing thumbnail.

Some form of garbage collection should be performed on thumbnail cache or the directories will fill up.


perl(1), Apache(3), Apache::Icon(3), Image::Magick(3) . Apache::AutoIndex(3)


Please send any questions or comments to the Apache modperl mailing list <> or to me at <>


This code was made possible by :

Philippe M. Chiasson

<> Creator of Apache::AutoIndex.

Doug MacEachern

<> Creator of Apache::Icon, and of course, mod_perl.

Rob McCool

Who produced the final mod_autoindex.c I copied, hrm.., well, translated to perl.

The mod_perl mailing-list

at <> for all your mod_perl related problems.


George Sanderson <>


Copyright (c) 2000-2001 George Sanderson All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Copyright (c) 1999 Philippe M. Chiasson. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

syntax highlighting: