Apache::OpenIndex - Perl Open Index manager for a Apache Web server SYNOPSIS PerlModule Apache::Icon PerlModule Apache::OpenIndex (PerlModule Apache::Language) optional (PerlModule Image::Magick) optional DESCRIPTION OpenIndex provides a file manager for a web sites through a web browser. It is a extensive rewrite of the Apache::AutoIndex.pm module which in turn was a remake of the autoindex Apache module. OpenIndex can provide the same functionality as AutoIndex.pm 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 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 "http://www.site.com/bob/" the following URL would be required: "http://www.site.com/bob/.XOI/" 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. 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 startup.pl file. Configuration Guidelines It is best to put the OpenIndex directives is in a 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 directive: 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: http:://www.site.com/friends/bob/ If a browser in turn accesses: http:://www.site.com/friends/bob/.XOI/ 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 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 , or 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: REMOTE_GROUP=1000 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. DIRECTIVES 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: http://www.apache.org/docs/mod/mod_autoindex.html 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 Apache::Icon.pm which provides icons to Apache::AutoIndex and Apache::OpenIndex. * FancyIndexing boolean The FancyIndexing directive tells OpenIndex to present a robust display which can include permissions, an icon, name, date, size, and description for each file and directory. All of the following autoindex and AutoIndex directives require FancyIndexing. * HeaderName file file ... Inserts a list of files displayed at the top of the document After Apache 1.3.5 the filename can be a relative URI. If the file name extention is '.html' it will be sent as is. * IndexIgnore file file A list of files not to be displayed. The files can specify extensions, partial names, wild card expressions, or full filenames. Multiple IndexIgnore directives add to the list. * IndexOptions [+|-]option [+|-]option ... There are several options. Please refer to the above URL: http://www.apache.org/docs/mod/mod_autoindex.html for the complete list. * IndexOrderDefault Ascending|Descending|Extension Name|Date|Size|Description IndexOrderDefault takes two arguments. The first must be either Ascending, Descending, or Extension indicating the direction of the sort. Only Name can have the Extension specified, which will sort on the file extension. The second argument must be one of the keywords: Name, Date, Size, or Description. It identifies the primary sort key. * ReadmeName file file ... A list of text files that will be displayed to the end of the document. If the file mime type is text/html it will be sent as is. * AddDescription "string" file file... The file description displayed for the given file (file name wild cards). * AddIconByEncoding (alttext, url) MIME-encoding MIME-encoding ... The file icon (alttext, url) to be displayed according to the MIME-encoding (mime-encoding). * AddIconByType (alttext, url) MIME-type MIME-type ... The file icon (alttext, url) to be displayed according to the MIME-type (mime-type). * AddIcon (alttext, url) name name ... The file icon (alttext, url) to be displayed according to file name extension. * DefaultIcon icon The file icon to be displayed if no other icon can be found. (default icon) AutoIndex DIRECTIVES * IndexOptions Thumbnails The listing will include thumbnails for pictures. Defaults to false. * IndexOptions ShowPermissions Print file permissions. Defaults to false. * IndexOptions SuppressHtmlPreamble When a header or footer file is included with the HeaderName file file ... ReadmeName file file ... directives, the and tags are striped. * IndexOptions FoldersFirst The folders will be presented first in the index listings. * IndexOptions HideExt The HideExt directive tells OpenIndex to not display the file extention within the index display. * IndexHtmlTag tag attributes This directive specifies the tag's attributes that will be inserted into the tag. For example: If the first character of attributes is a '+', it will append the following attributes to the current tag's attributes. If the first character of attributes is a '-' or not a '+', the current tag's attributes will be set to the following attributes string. Note that an initial '+' or '-' character is always striped. HINT: If you need to have the first line start with a '+' or a '-' character, use "-+ . . ." or "-- . . .". * IndexHtmlText tag [+|-]text This directive specifies the tag text that will be inserted within the tag. For example: text If the first character of text is a '+', it will append the following text to the current tag's text. If the first character of text is a '-' or not a '+', the current tag's text will be set to the following text. Note that an initial '+' or '-' character is always striped. HINT: If you need to have the first line start with a '+' or a '-' character, use "-+ . . ." or "-- . . .". The frameset tag is special in that you will need to place in the position where the index (main) frame is to be placed In this way any arbitrary frameset can be supported. HTML text can also be inserted just before each of the form text and submit buttons by appending 'insert' before it's name. For example to insert "Hello World" just before 'Browse' text field specify: IndexHtmlText InsertBrowse Hello World HINT: If the language option is enabled, the text will be looked up in order to support multiple languages. * IndexURIHead value Value should be the uri (absolute or relative) of a resource that would be inserted right after the tag and just before anything else. * IndexHtmlFoot value Value should be the uri (absolute or relative) of a resource that would be inserted right before the ending tag and after everything else. * IndexFrameTail value Value is a string that will be inserted after the main frame. The Frame option has to activated in order for this to work. The main frame contains the index table and is always inserted into the frameset. A NOFRAME tag is also always included. * IndexHtmlStyle value Value is a string that will be inserted inside the