CGI-FileManager

NAME

CGI::FileManager - Managing a directory structure on an HTTP server

SYNOPSIS

Enable authenticated users to do full file management on a subdirectory somewhere with a web server installed.

After installing the module you have to create a file with usernames and passwords in it. For this we supply cfm-passwd.pl which should have been installed in your PATH. Type:

> cfm-passwd.pl /home/user/mypwfile add someuser

It will ask for password and the home directory that the use is supposed to be able to manage.

Then in nearby CGI script:

     #!/usr/bin/perl -wT
     use strict;
 
     use CGI::FileManager;
     my $fm = CGI::FileManager->new(
                            PARAMS => {
                                    AUTH => {
                                            PASSWD_FILE => "/home/user/mypwfile",
                                    }
                            }
                    );
     $fm->run;

Now point your browser to the newly created CGI file and start managing your files.

WARNING

     This is Software is in Alpha version. Its interface, both human and programatic
     will change. If you are using it, please make sure you always read the Changes
     section in the documentation.

VERSION

Version 0.05

DESCRIPTION

Enables one to do basic file management operations on a filesystem under an HTTP server. The actions on the file system provide hooks that let you implement custom behavior on each such event.

It can be used as a base class for a simple web application that mainly manipulates files.

Methods
cgiapp_init
Initialize application (standard CGI::Application)

setup
Standart CGI::Appication method to setup the list of all run modes and the default run mode

cgiapp_prerun
Regular CGI::Application method

redirect
Just to easily redirect to the home page

load_tmpl
Change the default behaviour of CGI::Application by overriding this method. By default we'll load the template from within our module.

message
Print an arbitrary message to the next page

login_process
Processing the login information, checking authentication, configuring the session object or giving error message.

authenticate
Called without parameter. Returns an objects that is capable to authenticate a user.

By default it returns a CGI::FileManager::Auth object.

It is planned that this method will be overriden by the user to be able to replace the authentication back-end. Currently the requirements from the returned object is to have these methods:

     $a->verify(username, password)   returns true/false
     $a->home(username)               return the full path to the home directory of the given user

WARNING: this interface might change in the future, before we reach version 1.00 Check the Changes.

logout
logout and mark the session accordingly.

change_dir
Changes the current directory and then lists the new current directory

list_dir
Listing the content of a directory

delete_file
Delete a file from the server

remove_directory
Remove a directory

unzip
unzip

rename_form
Rename file form

rename
Rename file

upload_file
Upload a file

create_directory
Create a directory

DEFAULT
To get the default behavior you can write the following code. The module will use the built in templates to create the pages.

     #!/usr/bin/perl -wT
     use strict;
 
     use CGI::FileManager;
     my $fm = CGI::FileManager->new(
                            PARAMS => {
                                    AUTH => {
                                            PASSWD_FILE => "/home/user/mypwfile",
                                    }
                            }
                    );
     $fm->run;

new(OPTIONS)

META-DATA
Theoretically we could manage some meta-data about each file in some database that can be either outside our virtual file system or can be a special file in each directory.

Limitations
The user running the web server has to have read/write access on the relevant part of the file system in order to carry out all the functions.

USE CASES
Virtual web hosting with no ftp access for one user A single user needs authentication and full access to one directory tree. This does not work yet.

!/usr/bin/perl -T

     use CGI::FileManager;
     my $fm = CGI::FileManager->new({
                 ROOT => "/home/gabor/web/client1",
                 AUTH => ["george", "WE$%^DFRE"],   # the latter is the crypt-ed password we expect
                 });
     $fm->run;

Virtual web hosting with no ftp access for a number of users A number of users need authentication and full access to one directory tree per user.

#!/usr/bin/perl -T

     use CGI::FileManager;
     my $fm = CGI::FileManager->new(
                            PARAMS => {
                                    AUTH => {
                                            PASSWD_FILE => "/home/user/mypwfile",
                                    }
                            }
                    );
     $fm->run;

     The mypwfile file looks similar to an /etc/passwd file:
     username:password:uid:gid:geco:homedir:shell

     gid and shell are currently not used
     homedir is the directory the user has rights for
     password is encrypted by crypt
     uid is just a unique number

Changes
v0.01 2004 June 27

Initial release

v0.02_01

     Move file/directory
     Unzip file (.zip)

v0.02_02

     Separate CGI::FileManager::Templates
     add cfm-install.pl install script

     Use CGI::Application::Plugin::Session
     remove catching the warning of CA and require higher version of CA
     add a test that test a particular warning
     some subs were called as functions, now they are called as methods allowing better subclassing

TODO

install the module as regular CPAN module and add a script that will generate the templates and hard-code their location in the script.
Replace the Unix::ConfigFile with my own implementation

     Test the module on Windows and find out what need to be done to pass the windows
     tests ? Especially look at Unix::ConfigFile

     Show most of the error messages on the directory listing page
 
     Support for filenames with funny characters (eg. space)

     Test all the functions, look for security issues !
     Show the current directory  (the virtual path)
     Separate footer/header
     Enable external templates

     Security issues: can I be sure that unzipping a file will open files only under the current directory ?
     What should I do in case a file that comes from an unzip operation already exists ?

     ZIP: currently the path to unzip is hard coded. It probably should be replaced by Archive::Zip

     More fancy things:
     Create file
     Copy file/directory
     Unzip file (tar/gz/zip)
     Edit file (simple editor)

     look at CGI::Explorer and check what is the relationsip to it ?

Author

Gabor Szabo, "<gabor@pti.co.il>"

Bugs

Please report any bugs or feature requests to "bug-cgi-filemanager@rt.cpan.org", or through the web interface at <http://rt.cpan.org>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.