Perl Documentation

NAME

manage_files - rename/move/delete files

SYNOPSIS

<Location /files/>
    Plugin authenticate
    Plugin manage_files
    Plugin dir_to_xml
</Location>

DESCRIPTION

This module can be used to manage documents in your document root using plain HTML forms. It responds to certain query parameters and allows to rename, move, copy, delete and (limited) create files and directories.

Warning: This plugin allows extensive manipulation. Some more dangerous features are disabled by default, still you should not let just anyone manage files unless you understand exactly what happens here.

SECURITY

All file names are restricted to a simple and safe subset of ASCII, basically letters, numbers and some punctuation, but specifically not "..", shell metacharacters or other symbols that are known to be problematic. While this restriction doesn't need to be that strict in order to secure this plugin, in order to avoid problems with other programs processing these names, the default is quite conservative. See the ManageFilesCharset option to change this default.

Some operations are restricted:

* Symbolic links can be renamed, but not deleted if they point to a directory (even an empty one).

* Symlinks are followed, but subject to special treatment. See ManageFilesBasedir.

* Files can't be moved into other folders unless permitted by configuration.

* Even then, files can't be moved into the parent folder unless specially permitted.

* Directory manipulation is disabled by default.

* Directories can be removed only if they are empty.

ACTIONS

Usually, an XSLT stylesheet or similar should generate an HTML form from the source document or a directory listing. This plugin always works on the requested document, however, so an example HTML form to rename a file looks like this:

<form action="foo.jpg">
  Rename to: <input type="text" name="manage_files_rename">
  <input type="submit">
</form>

All actions are prefixed by manage_files_. Only relative file names are possible. Note that you must specify filenames with path components using "/" as path separator, regardless of server operating system.

rename

Renames a file. May also be used to move a file into other directories, if permitted by configuration.

delete

Deletes a file or directory (if it is empty, similar to rmdir). The parameter value must be "yes".

copy

Duplicates a file. (no directories)

mkdir

Creates a new subdirectory, if permitted by configuration. The target directory is the file being requested. The value of the request parameter is ignored.

upload

Creates a new file by uploading one. The target file is the file being requested, file data is the value of manage_files_upload. Multiple files can be uploaded as ZIP, .tar.gz, .tar.bz2 or 7-zip compressed archives if ManageFilesUploadArchives is true.

CONFIG

ManageFilesCharset REGEX

A regular expression that matches a single permitted character. Note that despite this option, a few dangerous file names and characters are always disallowed.

ManageFilemask REGEX_OR_WILDCARD

A regular expression/shell expression that restricts allowed filenames (both as source files and destination names). Note that despite this option, a few dangerous file names and characters are always disallowed.

ManageFilesAllow [ upload ] [ copy ] [ delete ] [ rename ]

Allowed file operations. Defaults to "rename".

ManageDirectoriesAllow [ mkdir ] [ copy ] [ delete ] [ rename ]

Allowed directory operations. Defaults to nothing allowed.

ManageFilesBasedir DIRECTORY

If this option is set, moving files between directories and subdirectories is allowed. Under no circumstance will files be moved outside the directory tree rooted at DIRECTORY. Symlinks are resolved to their true names before performing the test, so DIRECTORY should not contain symlinks.

ManageFilesUploadArchives BOOL

Auto-extract uploaded archives. The requested file must be the target directory. Files are extracted without path names.