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.02_03

Description
Methods
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.

  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)
    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.

  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

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.

Copyright & License
    Copyright 2004 Gabor Szabo, All Rights Reserved.
    <http://www.szabgab.com/>

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

See also
    CGI::Upload, WWW::FileManager, CGI::Uploader

