ReadMe for Dev-Editor 3.2
=========================

Description
-----------

Dev-Editor is a simple web based file manager written in Perl and licensed
under the terms of the Artistic License 2.0, allowing you to access a file
system on a server using a web browser. That's useful if you aren't able to
access the files directly or using FTP or SSH.

Features
--------

- Browsing through directory structures
- Viewing text files
- Editing text files
- Removing files and directories
- Moving/renaming files and directories
- Copying files and directories
- Creating new files and directories
- Executing a HTTP download of a file
- Uploading files to the server via HTTP
- Changing permissions (chmod) and group (chgrp) of files and directories (on
  Unix systems)
- Unpacking some types of archive files (Perl module Archive::Extract is
  required - core module since Perl 5.10, I guess)

Installation
------------

First, you have to copy the files into a directory on your web server where you
are able to execute CGI scripts (in most cases, this is "cgi-bin"). I suggest
to create a sub directory for Dev-Editor.
Then you have to change the first line of devedit.pl: Just replace
/usr/bin/perl by the path to your Perl interpreter.
If you are on a Unix based system, you have to make devedit.pl executable
(chmod 755 in most cases).
You also have to edit Dev-Editor's configuration file (see next section for
details).

If you install Dev-Editor on a public web server, you should protect its
directory using HTTP authentication or everybody in the world will be able to
access the configured directory structure!

Configuration
-------------

Open devedit.conf. This file contains keys and values separated by a "=" sign.
Lines beginning with a "#" sign are comments and will be ignored.
Here is a list of the configuration options currently available:

Option                   Description
------                   -----------

fileroot                 The root directory Dev-Editor is allowed to access.
                         Nobody is allowed to access the files and directories
                         above this directory. Dev-Editor needs write access to
                         this directory and its sub directories.

httproot                 This is the equivalent HTTP URL to the root directory.
                         It's just used for visual output, so it doesn't need to
                         be correct.

startdir                 Here you may define the default directory Dev-Editor
                         opens on start.

max_file_size            Here you may define a maximum size for files (Bytes).
                         If the user wants to view or edit a file larger than
                         this defined size, Dev-Editor denies file access (but
                         the file can still be copied, renamed or removed).
                         If this is empty or 0, any file can be viewed or
                         edited.

timeformat               The format of the time shown in directory listings.
                         These are the most important placeholders:

                         %a - short day name (Sun to Sat)
                         %A - long day name (Sunday to Saturday)
                         %b - short month name (Jan to Dec)
                         %B - long month name (January to December)
                         %d - day of the month (01 to 31)
                         %H - hour in 24 hour clock (00 to 23)
                         %I - hour in 12 hour clock (01 to 12)
                         %m - month of the year (01 to 12)
                         %M - minutes (00 to 59)
                         %p - AM or PM
                         %S - seconds (00 to 59)
                         %y - two digit year (03)
                         %Y - four digit year (2003)
                         %% - percent sign

                         There are a lot of other placeholders. A complete list
                         can be found at:
                         http://pubs.opengroup.org/onlinepubs/007908799/xsh/strftime.html
                         Note that some systems don't support some of the
                         placeholders (for example %T on Windows).

                         This format is also used to format the system time in
                         the About dialogue.

use_gmt                  Set this option to 1 if you want to use Greenwich Mean
                         Time (GMT/UTC) in directory listing and in the About
                         dialogue instead of the local time.

hide_dot_files           Set this option to 1 if you want to hide files or
                         directories beginning with a dot (e.g. ".htaccess") in
                         directory listing.
                         The files are just hidden in the directory listing,
                         you can still access them using the "Go to
                         directory/file" box.

forbidden                Specify a list of filenames the user is not allowed to
                         access. The filenames have to be relative to the
                         virtual root directory (they must also begin with a
                         slash) and have to be separated by space characters. If
                         a filename contains space characters, you have to put
                         it into double quotation marks ("/file name").

disable_commands         Specify a list of commands the user is not allowed to
                         execute. The commands have to be separated by space
                         characters.
                         If you add "@write" to the list, all writing commands
                         (for example edit, copy, rename etc.) will be
                         disabled.

userconf_file            Specifies the path to a file which contains
                         user-dependent configuration options (see next section
                         for details).

error_file               The path to the file which defines the error messages.
                         The file has the same format as the main configuration
                         file.

template_file            The path to the file which defines the paths to the
                         template files. The file has the same format as the
                         main configuration file.

User-dependent configuration
----------------------------

If you have placed Dev-Editor inside a directory protected using HTTP
authentication, you may override some default configuration values for a defined
list of users. You may override the values for the following configuration
options:

- fileroot
- httproot
- startdir
- hide_dot_files
- forbidden
- disable_commands

For overriding configuration values you need a special configuration file. The
path to this file is defined using the "userconf_file" configuration option in
the main configuration file (add the option if necessary). This file consists of
key-value-pairs and sections, marked by a string encapsulated in square brackets
(perhaps you know this format, it is nearly the same as Windows' INI files).
Each section in this file describes an individual configuration, whereby the
name of the section is the username for whom this configuration should be used.
Here is an example:

[homer]
fileroot = /var/www/homer/htdocs
httproot = /

This sets the physical file root directory to "/var/www/homer/htdocs" and the
virtual HTTP root to "/" - but only for the user whose HTTP authentication
username is "homer".

Using the "aliases" option, you may also define some other usernames for whom
this configuration should be used:

[homer]
fileroot = /var/www/homer/htdocs
httproot = /
aliases = marge bart

Using this, the users whose usernames are "marge" and "bart" use the same
configuration as "homer". You can place an arbitrary number of usernames
seperated by whitespaces here.
Note: If one of the users is defined as an alias and there is an individual
configuration section for this user too, the one defined as an alias is
ignored.

If there are some files marked as inaccessible using the "forbidden"
configuration option in the main configuration file, but some users should have
access to these files, you may clear the default value of "forbidden":

[homer]
fileroot = /var/www/homer/htdocs
httproot = /
forbidden =

Using this, "homer" has access to all files in "/var/www/homer/htdocs".

Notes
-----

Symbolic links are treated as files, no matter where they point to. The user is
just allowed to see the path where the link points to, he is allowed to delete
the link, to rename it and to overwrite it by renaming an other file. Nothing
else is allowed.
Accessing a symbolic link pointing to a directory also caused a very strange
effect: It was possible to access this directory, but you could not access the
objects in it.
I had to do it in this way because of the very stupid behaviour of abs_path()
from the Cwd module: This function is just able to detect the absolute path of
directories.
Hard links are not affected by this.

------------------------------------------------

(C) 1999-2000 Roland Bluethgen, Frank Schoenmann
(C) 2003-2011 Patrick Canterino

E-Mail: patrick@patshaping.de
WWW:    http://devedit.sourceforge.net/