version=pmwiki-2.2.5 ordered=1 urlencoded=1
agent=Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US) AppleWebKit/530.5 (KHTML, like Gecko) Chrome/2.0.172.43 Safari/530.5
author=Simon
charset=ISO-8859-1
csum=GroupCustomizations 
host=202.37.32.2
name=PmWiki.UploadsAdmin
rev=132
targets=PmWiki.PmWiki,PmWiki.Uploads,PmWiki.Security,PmWiki.WikiAdministrator,PmWiki.PasswordsAdmin,PmWiki.Passwords,PmWiki.GroupCustomizations,PmWiki.LocalCustomizations,PmWiki.WikiGroup,PmWiki.PageDirectives
text=(:title Uploads Administration:)%0a(:Summary:Administration of PmWiki [[uploads]]:)%0a[[PmWiki]] includes a script called ''upload.php'' that allows users to [[upload(s)]] 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.%0a%0a%0a!! Some notes about [[security]]%0a%0aPmWiki takes a somewhat, but justifiable, paranoid stance%0awhen it comes to the uploads feature.  Thus, the default settings for%0auploads tend to try to restrict the feature as much as possible:%0a%0a* The upload function is disabled by default%0a* Even if you enable it, the function is password locked by default%0a* Even if you remove the password, you're restricted to uploading files with certain names, extensions, and sizes%0a* The characters that may appear in upload filenames are (default) alphanumerics, hyphen, underscore, dot, and space ([[#restrictinguploadedfiles|see also here]]).%0a* The maximum upload size is small (50K by default)%0a%0aThis way the potential damage is limited until/unless the wiki%0aadministrator explicitly relaxes the restrictions.%0a%0aKeep 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 administrator]]s should be aware that the potential for vulnerabilities exist, and that misconfiguration of the upload utility could lead to unwanted consequences.%0a%0aBy 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'':%0a%0a->[@$EnableUploadOverwrite = 0;@]%0a%0aAlternatively, an administrator can [[#upload_versions|keep older versions]] of uploads.%0a%0aAn administrator can also [[#direct_download|configure]] PmWiki so the password mechanism controls access to uploaded files.%0a%0a%0a!! Basic installation%0a%0aThe ''upload.php'' script is automatically included from ''stdconfig.php'' if the $EnableUpload variable is true in ''config.php''.  In addition, ''config.php'' can set the $UploadDir and $UploadUrlFmt variables to specify the local directory where uploaded files should be stored, and the URL that can be used to access that directory.  By default, $UploadDir and $UploadUrlFmt assume that uploads will be stored in a directory called ''uploads/'' within the current directory (usually the one containing ''pmwiki.php'').  In addition, ''config.php'' should also set a default upload password (see [[PasswordsAdmin]]).%0a%0aThus, a basic ''config.php'' for uploads might look like:%0a%0a->[@%0a%3c?php if (!defined('PmWiki')) exit();%0a##  Enable uploads and set a site-wide default upload password.%0a$EnableUpload = 1;%0a$DefaultPasswords['upload'] = crypt('secret');%0a@]%0a%0aIf you have edit passwords and wish to allow all users with edit rights to upload, instead of $DefaultPasswords['upload'], you can set @@$HandleAuth['upload'] = 'edit';@@ in config.php.%0a%0a'''Important''': do NOT create the uploads directory yet! See the next paragraph.%0a%0aYou may also need to explicitly set which filesystem directory will hold uploads and provide a URL that corresponds to that directory like:%0a%0a->[@%0a$UploadDir = "/home/foobar/public_html/uploads";%0a$UploadUrlFmt = "http://example.com/~foobar/uploads";%0a@]%0a%0a[[#uploaddirectoryconfiguration]]%0a!!! Upload directory configuration%0aUploads can be configured site-wide, by-group, or by-page by changing $UploadPrefixFmt.  This determines whether all uploads go in one directory for the site, an individual directory for each group, or an individual directory for each page.  The default is to organize upload by group.%0a%0a[[#sitewideprefix]]For site-wide uploads, use%0a%0a->[@$UploadPrefixFmt = '';@]%0a%0aTo organize uploads by page, use:%0a->[@%0a$UploadPrefixFmt = '/$Group/$Name';%0a@]%0a%0a!!! The upload directory%0a%0aFor 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!''%0a%0a%0a!!! Uploading a file%0a%0aOnce the upload feature is enabled, users can access the upload form by adding "@@?action=upload@@" to the end of a normal PmWiki URL.  The user will be prompted for an upload password similar to the way other pages ask for passwords (see [[Passwords]] and [[PasswordsAdmin]] for information about setting passwords on pages, groups, and the entire site).%0a%0aAnother way to access the upload form is to insert the markup "[@Attach:filename.ext@]" into an existing page, where @@filename.ext@@ is the name of a new file to be uploaded.  When the page is displayed, a '?-link' will be added to the end of the markup to take the author to the upload page. (See [[Uploads]] for syntax variations.)%0a%0aBy default, PmWiki will organize the uploaded files into separate subdirectories for each group.  This can be changed by modifying the $UploadPrefixFmt variable. See [[Cookbook:UploadGroups]] for details.%0a%0a%0a!! [[#upload_versions]] Versioning Uploaded Files%0a%0aPmWiki does not manage versioning of uploaded files by default. However, by setting $EnableUploadVersions=1; an administrator can have older versions of uploads preserved in the uploads directory along with the most recent version.%0a%0a!! Upload restrictions%0a!!! Restricting uploaded files for groups and pages%0a%0aUploads can be enabled only for specific groups or pages by using a [[group customization(s)]].  Simply set @@$EnableUpload=1;@@ for those groups or pages where uploading is to be enabled; alternately, set @@$EnableUpload=1;@@ in the config.php file and then set @@$EnableUpload=0;@@ in the per-group or per-page customization files where uploads are to be disabled.%0a%0a!!! Restricting total upload size for a group or the whole wiki%0a%0aUploads can be restricted to an overall size limit for groups.  In the group configuration file (i.e., local/Group.php), add the line%0a%0a->$UploadPrefixQuota = 1000000;    # limit group uploads to 1000KB (1MB)%0a%0aThis 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).%0a%0aUploads can also be restricted to an overall size limit for all uploads.  Add the line%0a%0a->$UploadDirQuota = 10000000;    # limit total uploads to 10000KB (10MB)%0a%0aThis 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).%0a%0a%0a[[#restrictinguploadedfiles]]%0a!!!Restricting uploaded files type and size%0a%0aThe upload script performs a number of verifications on an uploaded file before storing it in the upload directory.  The basic verifications are described below.%0a:'''filenames''': the name for the uploaded file can contain only letters, digits, underscores, hyphens, spaces, and periods, and the name must begin and end with a letter or digit.  %0a:'''file extension''': only files with approved extensions such as "@@.gif@@", "@@.jpeg@@", "@@.doc@@", etc. are allowed to be uploaded to the web server.  This is vitally important for server security, since the web server might attempt to execute or specially process files with extensions like "@@.php@@", "@@.cgi@@", etc.  %0a:'''file size''': By default all uploads are limited to 50K bytes, as specified by the $UploadMaxSize variable.  Thus, to limit all uploads to 100KB, simply specify a new value for $UploadMaxSize in ''config.php'':%0a%0a->[@$UploadMaxSize = 100000;@]%0a%0aHowever, maximum file sizes can also be specified for each type of file uploaded.  Thus, an administrator can restrict "@@.gif@@" and "@@.jpeg@@" files to 20K, "@@.doc@@" files to 200K, and all others to the size given by $UploadMaxSize.  The $UploadExtSize array is used to determine which file extensions are valid and the maximum upload size (in bytes) for each file type.  For example:%0a%0a->[@$UploadExtSize['gif'] = 20000; # limit .gif files to 20KB@]%0a%0aSetting an entry to zero disables file uploads of that type altogether:%0a%0a->[@$UploadExtSize['zip'] = 0;     # disallow .zip files@]%0a%0aYou can limit which types of files are uploadable by disabling all defaults and specifying only desired types%0aSetting the variable $UploadMax to zero will disable all default file types. Individual file types may then be enabled by setting their maximum size with the variable $UploadExtSize.%0a%0a-> [@# turns off all upload extensions%0a$UploadMaxSize = 0;%0a%0a# enable only these file types for uploading%0a$aSize=100000; // 100 KB file size limitation%0a$UploadExtSize['jpg' ] = $aSize;%0a$UploadExtSize['gif' ] = $aSize;%0a$UploadExtSize['png' ] = $aSize;%0a@]%0a%0a[[#newuploadfiletypes]]%0a!! Adding new file types to permitted uploads%0a%0aTo add a new extension to the list of allowed upload types, add a line like the following to a [[local customization(s)]] file:%0a%0a->[@$UploadExts['ext'] = 'content-type';@]%0a%0awhere ''ext'' is the extension to be added, and ''content-type'' is the "[[(Wikipedia:)MIME type]]", or content-type (which you may find %25newwin%25[[http://www.iana.org/assignments/media-types/ | here]] or on the lower part of %25newwin%25[[http://www.w3schools.com/media/media_mimeref.asp | this page]]) to be used for files with that extension.  For example, to add the '[@dxf@]' extension with a Content-Type of '[@image/x-dxf@]', place the line%0a%0a->[@$UploadExts['dxf'] = 'image/x-dxf';@]%0a%0aEach entry in $UploadExts needs to be the extension and the%0amime-type associated with that extension, thus:%0a%0a->[@%0a$UploadExts = array(%0a  'gif' => 'image/gif',%0a  'jpeg' => 'image/jpeg',%0a  'jpg' => 'image/jpeg',%0a  'png' => 'image/png',%0a  'xxx' => 'yyyy/zzz'%0a);%0a@]%0a%0aFor 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).%0a[[#newuploadfiletypesend]]%0aSee also Cookbook:UploadTypes for additional types.%0a%0a[[#otherfilesizelimits]]%0a!!Other file size limits%0a%0aThere are other factors involved that affect upload file sizes.  In Apache 2.0, there is a `[[http://httpd.apache.org/docs/2.2/mod/core.html#limitrequestbody|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''.)%0a%0aProblem 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.%0a%0aPHP itself has two limits on file uploads (usually located in @@/etc/php.ini@@).  The first is the @@upload_max_filesize@@ parameter, which is set to 2MB by default.  The second is @@post_max_size@@, which is set to 6MB by default.%0a%0aWith 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.%0a%0a!!! [[#direct_download]] Password protecting uploaded files%0aSetting 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:%0a %0a* In local/config.php set @@$EnableDirectDownload=0@@;%0a* If you use per-group upload directories (PmWiki default, see $UploadPrefixFmt), add to config.php @@$EnableUploadGroupAuth = 1;@@%0a* Deny public access to the uploads/ directory through moving it out of the html/ or public_html/ directory tree, or through a .htaccess file.%0a%0a%0aSee [[Cookbook:Secure attachments]] {Cookbook.SecureAttachments$:Summary}%0a%0a%0a!! Other notes%0a%0a* If uploads doesn't seem to work, make sure that your PHP installation allows uploads.  The ''php.ini'' file (usually ''/etc/php.ini'' or ''/usr/local/lib/php.ini'') should have  %0a%0a->[@file_uploads = On@]%0a%0aNote that if you change this value, httpd must generally be restarted.  Another way to check if uploads are allowed by the server is to set $EnableDiag to 1 in ''config.php'', and set ?action=phpinfo on a URL. The "@@file_uploads@@" variable must have a value of 1 (if it says "@@no value@@", that means it's off).%0a%0a%0a%0a%0a>>faq%3c%3c [[#faq]]%0a%0aQ: How do I disable uploading of a certain type of file?%0aA: Here's an example of what to add to your ''local/config.php'' file to disable uploading of .zip files:%0a%0a->[@$UploadExtSize['zip'] = 0;  # Disallow uploading .zip files.@]%0a%0a%0aQ: How do I attach uploads to individual pages or the entire site, instead of organizing them by [[wiki group]]?%0aA: Use the $UploadPrefixFmt variable (see also the Cookbook:UploadGroups recipe).%0a%0a->[@$UploadPrefixFmt = '/$FullName';  # per-page@]%0a->[@$UploadPrefixFmt = '';   # site-wide@]%0a%0aQ:For $UploadDirQuota - can you provide some units and numbers?  Is the specification in bytes or bits? What is the number for 100K? 1 Meg? 1 Gig? 1 Terabyte?%0aA: Units are in bytes. %0a%0a   $UploadDirQuota = 100*1024;         # limit uploads to 100KiB%0a   $UploadDirQuota = 1000*1024;        # limit uploads to 1000KiB%0a   $UploadDirQuota = 1024*1024;        # limit uploads to 1MiB%0a   $UploadDirQuota = 25*1024*1024;     # limit uploads to 25MiB%0a   $UploadDirQuota = 2*1024*1024*1024; # limit uploads to 2GiB%0a%0aQ: Is there a way to allow file names with Unicode or addtiional characters? %0aA: Yes, see $UploadNameChars%0a%0aQ:Where is the list of attachments stored?%0aA: It is generated on the fly by the [[PageDirectives#attachlist|(:attachlist:)]] markup.%0a%0aQ: How can I find orphaned or missing attachments%0aA: See [[Cookbook:Attachlist enhanced]] {Cookbook.AttachlistEnhanced$:Summary}%0a%0aQ: How can I prevent hotlinking of my uploaded images%0aA: See [[Cookbook:Prevent Hotlinking]] {Cookbook.PreventHotlinking$:Summary}%0a%0aQ: I have limited the max upload size to 8 MB in config.php, however only files smaller than 2MB can be uploaded.%0aA: Check your php.ini for ''upload_max_filesize''%0a->[@%0aupload_max_filesize = 8M%0a@]%0a
time=1251406724
title=Uploads Administration