PmWiki includes a script called upload.php that allows users to upload files to the wiki server using a web browser. Uploaded files (also called attachments) can then be easily accessed using markup within wiki pages. This page describes how to install and configure the upload feature.
Some notes about security
PmWiki takes a somewhat, but justifiable, paranoid stance when it comes to the uploads feature. Thus, the default settings for uploads tend to try to restrict the feature as much as possible:
This way the potential damage is limited until/unless the wiki administrator explicitly relaxes the restrictions.
Keep in mind that letting users (anonymously!) upload files to your web server does entail some amount of risk. The upload.php script has been designed to reduce the hazards, but wiki administrators should be aware that the potential for vulnerabilities exist, and that misconfiguration of the upload utility could lead to unwanted consequences.
By default, authorized users are able to overwrite files that have already been uploaded, without the possibility of restoring the previous version of the file. If you want to disallow users from being able to overwrite files that have already been uploaded, add the following line to config.php:
Alternatively, an administrator can keep older versions of uploads.
An administrator can also configure PmWiki so the password mechanism controls access to uploaded files.
The upload.php script is automatically included from stdconfig.php if the
Thus, a basic config.php for uploads might look like:
<?php if (!defined('PmWiki')) exit(); ## Enable uploads and set a site-wide default upload password. $EnableUpload = 1; $UploadPermAdd = 0; $DefaultPasswords['upload'] = pmcrypt('secret');
Important: do NOT create the uploads directory yet! See the next paragraph.
You may also need to explicitly set which filesystem directory will hold uploads and provide a URL that corresponds to that directory like:
$UploadDir = "/home/foobar/public_html/uploads"; $UploadUrlFmt = "http://example.com/~foobar/uploads";
Note: In most installations, you don't need to define or change these variables, usually PmWiki can detect them (and if you do, uploads may simply not work).
Upload directory configuration
Uploads can be configured site-wide, by-group (default), or by-page by changing
Single upload directory
Per page upload directories
To organize uploads by page, use:
You may prefer uploads attached per-page rather than per-group or per-site if you plan to have many files attached to individual pages. This setting simplifies the management of picture galleries for example. (In a page, you can always link to attachments to other pages.)
The upload directory
For the upload feature to work properly, the directory given by $UploadDir must be writable by the web server process, and it usually must be in a location that is accessible to the web somewhere (e.g., in a subdirectory of public_html). Executing PmWiki with uploads enabled will prompt you with the set of steps required to create the uploads directory on your server (it differs from one server to the next). Note that you are likely to be required to explicitly create writable group- or page-specific subdirectories as well!
Uploading a file
Once the upload feature is enabled, users can access the upload form by adding "
Another way to access the upload form is to insert the markup "
PmWiki does not manage versioning of uploaded files by default. However, by setting
Restricting uploaded files for groups and pages
Uploads can be enabled only for specific groups or pages by using a group customization. Simply set
Restricting total upload size for a group or the whole wiki
Uploads can be restricted to an overall size limit for groups. In the group configuration file (i.e., local/Group.php), add the line
This will limit the total size of uploads for that group to 1000KB --any upload that pushes the total over the limit will be rejected with an error message. This value defaults to zero (unlimited).
Uploads can also be restricted to an overall size limit for all uploads. Add the line
This will limit the total size of uploads for the whole wiki to 10000KB --any upload that pushes the total over the limit will be rejected with an error message. This value defaults to zero (unlimited).
Restricting uploaded files type and size
The upload script performs a number of verifications on an uploaded file before storing it in the upload directory. The basic verifications are described below.
However, the default maximum file size can also be specified for each type of file uploaded. Thus, an administrator can restrict "
$UploadExtSize['zip'] = 0; # disallow .zip files $UploadExtSize[''] = 0; # disallow files with no extension
You can limit which types of files are uploadable by disabling all defaults and specifying only desired types.
Setting the variable
# turns off all upload extensions $UploadMaxSize = 0; # enable only these file types for uploading $aSize=100000; // 100 KB file size limitation $UploadExtSize['jpg' ] = $aSize; $UploadExtSize['gif' ] = $aSize; $UploadExtSize['png' ] = $aSize;
Note: Files with multiple extensions
Some installations with the Apache server will try to execute a file which name contains ".php", ".pl" or ".cgi" even if it isn't the last part of the filename. For example, a file named "test.php.txt" may be executed. To disallow such files to be uploaded, add to config.php such a line:
Adding new file types to permitted uploads
To add a new extension to the list of allowed upload types, add a line like the following to a local customization file:
where ext is the extension to be added, and content-type is the "MIME type", or content-type (which you may find here or on the lower part of this page) to be used for files with that extension. For example, to add the '
Each entry in $UploadExts needs to be the extension and the mime-type associated with that extension, thus:
$UploadExts = array( 'gif' => 'image/gif', 'jpeg' => 'image/jpeg', 'jpg' => 'image/jpeg', 'png' => 'image/png', 'xxx' => 'yyyy/zzz' );
For the types that PmWiki already knows about it's not necessary to repeat them here (the upload.php script adds PmWiki's defaults to whatever the administrator supplies). See also Cookbook:UploadTypes for additional types.
Other file size limits
There are other factors involved that affect upload file sizes. In Apache 2.0, there is a `LimitRequestBody directive that controls the maximum size of anything that is posted (including file uploads). Apache has this defaulted to unlimited size. However, some Linux distributions (e.g., Red Hat Linux) limit postings to 512K so this may need to be changed or increased. (Normally these settings are in an httpd.conf configuration file or in a file in /etc/httpd/conf.d.)
Problem noted on Red Hat 8.0/9.0 with Apache 2.0.x, the error "Requested content-length of 670955 is larger than the configured limit of 524288" was occurring under Apache and a "Page not found" would appear in the browser. Trying the above settings made no change with PHP, but on Red Hat 8.0/9.0 there is an additional PHP config file, /etc/httpd/conf.d/php.conf, and increasing the number on the line "LimitRequestBody 524288" solves the issue.
PHP itself has two limits on file uploads (usually located in
With the variables in place--PmWiki's maximum file size, Apache's request-size limits, and the PHP file size parameters, the maximum uploaded file size will be the smallest of the three variables.
Setting a read password for pages (and groups) will prevent an attached file from being seen or accessed through the page, but to prevent direct access to the file location (the uploads/ directory) one can do the following:
See Cookbook:Secure attachments Security issues for attachments
Note that if you change this values, httpd must generally be restarted. Another way to check if uploads are allowed by the server is to set
How do I disable uploading of a certain type of file?
Here's an example of what to add to your local/config.php file to disable uploading of .zip files, or of files with no extension:
$UploadExtSize['zip'] = 0; # Disallow uploading .zip files $UploadExtSize[''] = 0; # Disallow files with no extension
How do I attach uploads to individual pages or the entire site, instead of organizing them by wiki group?
Units are in bytes.
Is there a way to allow file names with Unicode or additional characters?
Where is the list of attachments stored?
It is generated on the fly by the (:attachlist:) markup.