File Manager plugin for SquirrelMail
====================================
Ver 1.5, 10/26/02

Original author: Paul Lesneiwski <pdontthink@angrynerds.com>

Endless thank-yous  (a.k.a. Credits):
   Ryan <ryan@vendetta.com> 
      Lots of good ideas, programming tips and debug help.
   Kenneth G. Kirk <kkirk@christtheteacher.org>
      Wrote a kick-ass README!  Also, tons of ideas, 
      endless testing.
   Rene <rene.madsen@webscorpion.com>
      Help debugging and flushing out those hard to find 
      problems...
   Hans Pech <hanspech@gmx.net>
      Wrote the German translation - whew!  Also, lots of
      patience helping me debug.
   Ken Wilson <kaw@wilberforce.ac.uk>
      Wrote a very nice little shell script to automate
      config file population!  Also helped find those 
      little hard-to-find bugs.



Description
===========

This plugin allows designated users file management
access to a pre-defined portion of the host machine's
file system.  

Probably doesn't work in Windows hosting environment,
but if anyone's willing to serve as a test dummy, I'm 
sure we can fix that...


Basic User Features
===================

  *  Create/Delete/Rename/Move/Copy files/directories
  *  File upload/download (includes overwrite warnings)
  *  Edit files
  *  Save attachments locally or send files as email attachments
  *  Point-n-click directory navigation

  
Advanced/Admin Features (dynamically controlled by config.php)
==============================================================

  *  Per-user access to plugin
  *  Per-user base directory configuration (can have multiple)
  *  Per-user quota control (dynamically re-calculated)
  *  Per-user access to symbolic links
  *  Per-user access to chmod
  *  Global - disable all chmod functionality (for use on
     systems where php was compiled without chmod support)


Configuration - (set by editing config.php)
==========================================

Global settings:

  * $systemUmask is currently only used when creating
    new directories. Change with care!

  * $defaultFolderPerms sets the permissions that will
    be used when creating new directories. Change as needed.

  * $defaultFilePerms sets the permissions that will be
    used when creating/uploading new files. Change as needed.
    
  * $symlinkColor sets the color for symbolic link display.
    Set to '' for default link color. Change as needed.

  * $fileEditStyle controls how the edit feature is accessed
    'edit link' displays [Edit] to the right of the filename.
    'hyperlink' displays the filename as a hyperlink
    
  * $fileLinkColor sets the color for the 'hyperlink' option
    of the $fileEditStyle. Set to '' for default link color.
    Change as needed.
    
  * $chmodOK indicates if the chmod command is available on
    the host system (and support for it is compiled into php).
    This can be set to '0' if no chmod commands should be
    allowed. When set to '1' only authorized users will have
    access. (see allowChmod below...) Most users of this plugin
    won't need to change this setting! Those who do probably 
    know who you are. Change with care!


User settings: (only named users will have access to the file_manager)

      'user2@domain.net' => array(
         'baseDir' => '/www/user2/html',
         'quota' => '5MB',
         'adminMail' => 'help@yet.another.domain.org',
         'allowLinks' => 1,
         'allowChmod' => 0
      ),

  * repeat this block in the config.php file for each user who
    needs access to the file_manager.
  
  * 'user2@domain.net' should match the user's exact login ID
    (that is, SquirrelMail's $username contents).  Of course,
    some systems do not require the '@domain.net'. This must 
    precisely match the users login ID!  
    (Change $debug in setup.php to 1 to see a printout of 
    $username in place of the regular File Manager link if 
    there is any doubt.)

  * baseDir1 defines the home directory to which the user will
    have access. It is used as the top-level of the user's access.
    Use caution with this setting as the user will have access to
    all files and sub-directories. Most likely this must be set to
    the absolute directory path. Use caution, you don't want to
    give away the store!
    
  * baseDir2 You may define as many base directories as needed
    by adding a new suffix to each baseDir entry.

  * quota defines the user's storage allowance. Storage used is
    calculated by adding up the size of all files in the baseDir
    and any sub-directories of the baseDir. When set to '' the user
    is allowed unlimited storage.  NOTE: for users with more than
    one base directory, the quota applies PER directory, not in total.
    
  * adminMail defines what address will be shown to the user for 
    problem determination and resolution. The address will be
    displayed as a mailto: hyperlink when the user encounters an
    error.
    
  * allowLinks determines if symbolic links will be displayed to 
    the user. If set to 1, the user will have access to any files
    and directories referenced in or below the link. Enable this 
    option with extreme care!
    
  * allowChmod allows the user to change the file/folder permissions
    on accessible files. When set to 1 the user is allowed, when set
    to 0 the user is not allowed. This option is dependant on the 
    global option chmodOK and is only available if it is set to 1.



Security Notes
==============
Users will only be able to manipulate files which
php will have permission to change, which in most
cases means that they (and containing directory if it
is a file in question) will need to be owned by the
user defined by the web server.  In the case of apache,
you'll want to do something like this (replace "apache" 
with "nobody" or as appropriate in your case):

  $ chown -R apache:apache users/base/directory
  
  or
  
  $ chown -R root:apache users/base/directory

The directory information passed to the client browser
is always relative; however, this is not to say that 
that scheme might not be circumvented somehow.  Every 
request is first checked against the user's base 
directory, and no requests are acted upon above that 
directory, but again, someone with more knowledge on 
security breaches should review this code for potential 
holes.



Change Log
==========
  1.5 - Paul Lesneiwski <pdontthink@angrynerds.com>
   * Save email attachments locally (to host server)
   * Send any file as an email attachment 
     (the edit/view/download/send links are beginning 
     to crowd the page layout; you might want to try 
     using the $fileEditStyle='hyperlink' setting)
   * Multiple file upload functionality
   * Multiple base directory configuration option
     (going forward, you should update your config
     file with "baseDir1" instead of "baseDir", however,
     it is backward compatible without making any config
     changes!)
   * Added sample script to automate the population of
     the config file for large user bases (complements
     Ken Wilson <kaw@wilberforce.ac.uk>)
   * Added compatibility for plugin updates tool
   * Internationalization!  Translators wanted - email
     me if you're interested.

  1.4.5 - Paul Lesneiwski <pdontthink@angrynerds.com>
   * New README file - please do READ it!  (Kenneth G. 
     Kirk <kkirk@christtheteacher.org> gets all the 
     credit for this thankless job (THANKS!!!).)
   * Minor bug fix checking upload file size (thanks 
     to Jimmy Conner <jimmy@advcs.org>)
   * Fixed BACK link that wasn't working in some 
     environments (thanks to Matthew Kennedy's
     <mkennedy@dnetworking.com> patience testing!).
   * Suppress warnings when calculating quota

  1.4 - Paul Lesneiwski <pdontthink@angrynerds.com>
   * Implemented quota checking
   * Added Revert button when editing a file
   * Removed old code that was accidentally placing
     temp files in the SM attachments directory

  1.3 - Paul Lesneiwski <pdontthink@angrynerds.com>
   * Implemented copy functionality
   * CHMOD now works on all selected items
   * Moved edit from the button row to be a link
   * Symlinks get some color!
   * BACK link at bottom of file list
   * File edit link can also by a hyperlink (w/custom
     color)
   * Fixed bug when downloading nonexistent files 
     (thanks to Ryan <ryan@vendetta.com>)
   * Added $chmodOK to allow sysadmins to turn off
     all chmod code in the entire plugin in one place

  1.2 - Paul Lesneiwski <pdontthink@angrynerds.com>
   * Added file download/view functionality (tons of
     thanks to Ryan <ryan@vendetta.com> for the ideas
     and help!)
   * Added file sorting 
   * Added CHMOD functionality (can turn on/off per user)
     (thanks to Kenneth G. Kirk <kkirk@christtheteacher.org> 
     for tips and testing this and many other functions)
   * Disallow user to view symlinks (can turn on/off
     per user)
   * Added move/rename functionality.  User must enter
     path manually (I'd like to provide a way for them
     to browse in a popup window or the likes and select
     the target by clicking on it).  Protection is 
     included to disallow moving anything above the
     user's base directory.
   * Made default permissions (and umask) used when creating 
     files and directories configurable.

  1.1 - Paul Lesneiwski <pdontthink@angrynerds.com>
   * Disallow users from attempting to edit directories
   * Potential security hole when uploading files fixed 
     (props to Ryan <ryan@vendetta.com>!!)
   * Protect files from being overwritten unless user
     checks a checkbox
   * Dynamic "smart" file name checks to avoid getting
     a message about duplicate file names AFTER waiting
     for a (possibly large) file to upload.

  1.0 - Paul Lesneiwski <pdontthink@angrynerds.com>
   * Initial release.


Future Work
===========

   *  Move files function -- need a clean way for
      user to select target directory.  Pop up a
      small window where the user can browse to
      the target?

   *  CHMOD functionality - perhaps it would be nice
      to give a graphical way to choose permissions
      instead of asking for the octal number!

   *  Limit editing of files to text files only.
      (How?  Using file extensions is easy, but not 
      a definitive solution.)

   *  Allow limited access to file execution or 
      certain tools (untar/unzip, etc)??  From
      a security perspective, this may be disasterous.

