Manual:Configuring file uploads
MediaWiki supports uploading and integration of media files. This page describes the technical aspects of this feature, see Manual:Image Administration and Help:Images for general usage information.
Starting from MediaWiki version 1.1, uploads are initially disabled by default, due to security considerations. Uploads can be enabled via a configuration setting, although it is recommended that you check certain prerequisites first:
[edit] Prerequisites
[edit] Make sure uploads are enabled in PHP
The following needs to be set in php.ini (which may be located somewhere like /etc/php/php.ini, /etc/php4/php.ini, /etc/php5/cli/php.ini & /etc/php5/apache2/php.ini (openSUSE 11.2), /usr/local/lib/php.ini or on Win32 C:\Windows\php.ini):
file_uploads = On
If this is not set, PHP scripts cannot use the upload functions, and MediaWiki's uploads will not be enabled.
If the open_basedir directive is set, it must include both the destination upload folder in your MediaWiki installation ("{$IP}/images") and the 'upload_tmp_dir' folder (default system folder if not set). The addition of the 'upload_tmp_dir' can avoid messages like "Could not find file "/var/tmp/php31aWnF" (where in this example the 'upload_tmp_dir' is '/var/tmp'). Read more about PHP file uploads at File upload basics and in particular move_uploaded_file.
Note: The formal value for the variable is a boolean expression. PHP treats each string not recognised as a False value as true, hence the often used "on" value yields the same result.
[edit] Check for Windows and IIS users
Set %SystemRoot%\TEMP to have permissions for the Internet Guest Account (IUSR_MachineName, or IUSR for IIS 7+): Read, write and execute;
[edit] Check directory security
The upload directory needs to be configured so that it is not possible for an end user to upload and execute other scripts, which could then exploit access to your web directory and damage your wiki or web site.
Set the /images folder (or the /uploads folder in previous versions) to have permission "755":
- User can read, write and execute;
- Group can read and execute;
- World can read and execute.
If using safe_mode, make sure the directory is owned by the user used for running the php script (that is, the apache user or, in case of suphp, the script owner).
If using SELinux, make sure to adjust the ACLs accordingly (see there).
If using suphp, make sure the umask is set to 0022 (or less) in /etc/suphp.conf.
- Restrict directory listing on images folder
If you don't want a public user to list your images folder, an option is to set this up in your apache configuration:
<Directory /var/www/wiki/images> Options -Indexes </Directory>
[edit] Setting uploads on/off
MediaWiki version: | ≥ 1.5 |
In MediaWiki version 1.5 and later, the attribute to be set resides in LocalSettings.php and $wgEnableUploads is set as follows:
$wgEnableUploads = true; # Enable uploads
This enables uploads, as one might expect. To disable them, set the attribute to false:
$wgEnableUploads = false; # Disable uploads
MediaWiki version: | ≤ 1.4 |
In older versions of the software, the attribute to be set resides in LocalSettings.php, but is backwards, i.e. $wgDisableUploads. The default is as shown:
$wgDisableUploads = true; # Disable uploads
Invert the value to enable uploads:
$wgDisableUploads = false; # Enable uploads
[edit] Upload permissions
Per default, all registered users can upload files. To restrict this, you have to change $wgGroupPermissions:
- To prevent normal users from uploading files:
$wgGroupPermissions['user']['upload'] = false; - To create a special group called "uploadaccess", and allow members of that group to upload files:
$wgGroupPermissions['uploadaccess']['upload'] = true; - To allow "autoconfirmed" (non-newbie) users to upload files:
$wgGroupPermissions['autoconfirmed']['upload'] = true;
The right to replace existing files is handled by an extra permission, called reupload:
- To prevent normal users from overriding existing files:
$wgGroupPermissions['user']['reupload'] = false; - To allow "autoconfirmed" (non-newbie) users to replace existing files:
$wgGroupPermissions['autoconfirmed']['reupload'] = true;
If a ForeignFileRepo is set, the right to replace those files locally is handled by an special permission, called reupload-shared:
- To prevent normal users from overriding filerepo files locally:
$wgGroupPermissions['user']['reupload-shared'] = false; - To allow "autoconfirmed" (non-newbie) users to replace filerepo files locally:
$wgGroupPermissions['autoconfirmed']['reupload-shared'] = true;
See Manual:User rights for details on user rights, and Manual:Preventing access for more information about restricting access.
[edit] Configuring file types
You can add $wgFileExtensions in LocalSettings.php to allow uploads of other desired file types. For example, you can change the $wgFileExtensions line to look something like
$wgFileExtensions = array('png','gif','jpg','jpeg','doc','xls','mpp','pdf','ppt','tiff','bmp','docx', 'xlsx', 'pptx','ps','odt','ods','odp','odg');
or
$wgFileExtensions = array_merge($wgFileExtensions, array('doc', 'xls', 'mpp', 'pdf','ppt','xlsx','jpg','tiff','odt','odg','ods','odp'));
or
# Add new types to the existing list from DefaultSettings.php $wgFileExtensions[] = 'doc'; $wgFileExtensions[] = 'xls'; $wgFileExtensions[] = 'pdf'; $wgFileExtensions[] = 'mpp'; $wgFileExtensions[] = 'odt'; $wgFileExtensions[] = 'ods';
However, certain file extensions are blacklisted ($wgFileBlacklist) and cannot be uploaded even if added to $wgFileExtensions. To upload files with blacklisted extensions, you must modify the blacklist. For instance, to allow users to upload executables:
$wgFileExtensions[] = 'exe'; $wgFileBlacklist = array_diff( $wgFileBlacklist, array ('exe') );
In addition, $wgMimeTypeBlacklist prevents certain file types based on MIME type; .zip files, for example, are prohibited based on MIME type (MediaWiki version 1.14 up to 1.17).
You can also set $wgStrictFileExtensions
$wgStrictFileExtensions = false;
to allow most types of file to be uploaded. However, blacklisted filetypes and MIME types will still not be permitted.
![]() |
Setting $wgStrictFileExtensions to false, or altering $wgFileBlacklist could result in either you or your users being exposed to security risks. |
If you are getting the error "The file is corrupt or has an incorrect extension", make sure mime type detection is working properly.
If you decide to allow any kind of file, make sure your mime detection is working and think about enabling virus scans for uploads.
[edit] Logon
By default anonymous uploads are not allowed. You must register and logon before the upload file option appears in the toolbox.
[edit] Thumbnailing
For information about automatic rendering/thumbnailing of images, see Manual:Image_thumbnailing. For problems with thumbnailing, see Image Thumbnails not working and/or appearing.
MediaWiki version: | ≥ 1.11 |
If the file is not visual (like an Image or Video) a fileicon is used instead. These are generated by the iconThumb()
function in the File class in the FileRepo group. Icons stored in "$wgStyleDirectory/common/images/icons/
" in a "fileicon-$extension.png
"-format.
[edit] Set maximum size for file uploads
By default, the configuration code in php.ini limits the size of files to be uploaded to 2 megabytes (and the maximum size of a post operation to 8 megabytes). To allow uploading of larger files, edit these parameters in php.ini:
This may require root access to the server. (If you are on a shared host, contact your server administrator.)
- Locating the php.ini file
The location of the php.ini file varies on the distribution you are using. (Try "locate php.ini" or "php -i" to find the location of your config file.)[3]
It is important to change the php.ini file in the apache2 folder. For example, there may be a core default php.ini at /etc/php5/cli/php.ini as well as one at /etc/php5/apache2/php.ini. If you are using mod_php (most common), it is the php.ini file in /etc/php5/apache2 that is important to change. For php-fastcgi, edit /etc/php5/cgi/php.ini.
- Multiple websites hosted on a server
If you have more than one website hosted on a server and want to change only for Mediawiki, insert into your /etc/apache2/sites-enabled/your_wiki_site.com inside <Virtual Host>:
php_value upload_max_filesize 20M php_value post_max_size 20M
Both above settings also work in a .htaccess file if your site uses mod_php. If your site uses PHP >= 5.3 and allows it, you can place php.ini directives in .user.ini files instead.
- web server limits
Your web server may impose further limits on the size of files allowed for upload. For Apache, one of the relevant settings is LimitRequestBody.[4] For Nginx, client_max_body_size is the relevant setting.[5] For Lighttpd, server.max-request-size is what may need modification.[6]
Note: You may need to restart Apache or IIS after altering your PHP or web server configuration. (sudo /etc/init.d/apache2 restart in Linux, for example.)
- uploading too large of files warning
MediaWiki itself issues a warning if you try to upload files larger than what is specified by $wgUploadSizeWarning option. This is independent of the hard limit imposed by PHP. MediaWiki also has a $wgMaxUploadSize option, but that is currently not enforced for normal uploads (when uploading a local file). The only way of restricting the upload size is through the use of modifying the php configuration.
- temporary upload limits
Temporary changes to upload limits (when using multiple wikis on a farm, for example) can be altered by adding the lines:
ini_set( 'post_max_size', '50M' ); ini_set( 'upload_max_filesize', '50M' );
to the MediaWiki LocalSettings.php configuration file for each wiki. In this example the PHP limit is set at 50 Mb. Note that these settings will not override the maximum settings set above (since the core php.ini and apache2 php.ini files set the absolute maximum). This method sets maximums that are less than the absolute maximum.
- IIS7 upload limit
Note: By default, IIS7[7] on Windows 2008 allows only 30MB to be uploaded via a web application. Larger files will return a 404 error after the upload. If you have this problem, you can solve it by increasing the maximum file size by adding the following code to <system.webServer> in the web.config file:
<security> <requestFiltering> <requestLimits maxAllowedContentLength="50000000" /> </requestFiltering> </security>
With the above maxAllowedContentLength, users can upload files that are 50,000,000 bytes (50 MB) in size. This setting will work immediately without restarting IIS services. The web.config file is located in the root directory of your web site.
To allow uploading files up to 2G:
add the following lines to LocalSettings.php:
$wgUploadSizeWarning = 2147483648; $wgMaxUploadSize = 2147483648;
Also, modify the following lines in PHP.INI:
memory_limit = 2048M (this line may not be necessary) post_max_size = 2048M upload_max_filesize = 2048M
In the IIS web.config file, override the value of maxRequestLength. For example, the following entry in web.config allows files that are less than or equal to 2 gigabytes (GB) to be uploaded:
<httpRuntime maxRequestLength="2097151" executionTimeout="18000"/>
With IIS 7, you also need to configure it to allow large uploads. This is found by clicking “Request Filtering > Edit Feature Settings” in the IIS section in the middle of the window. Set the ”Maximum allowed content length (Bytes)” field to 2147482624. If you don’t see "Request Filtering" in the IIS section, it needs enabled via Internet Information Services > World Wide Web Services > Security in the "Turn Windows features on or off" area in Control Panel.
If the above tip does not enable large uploads, then open a command prompt and execute this command as well:
%windir%\system32\inetsrv\appcmd set config -section:requestFiltering -requestLimits.maxAllowedContentLength: 2147482624
[edit] Allowing Java Script Uploads
$wgAllowJavaUploads = true;
If you're depending on Javascript in your site to perform various operations, without this setting, mimetypes will not be correctly detected. For example, no matter the ext list you provide and mimetype checking you invoke or prohibit, you will receive the message:
- The file is a corrupt or otherwise unreadable ZIP file. It cannot be properly checked for security.
if you attempt to upload a .doc file. Some believe that .doc are some form of .zip, thus causing confusion. This is untrue. MS .doc files are a proprietary mess. The newer .docx are .zip files.
[edit] Uploading directly from a URL ("Sideloading")
If you want to allow a user to directly upload files from a URL, instead of from a file on their local computer, set $wgAllowCopyUploads = true. On the upload form, you will then see an additional field for the URL, below the usual filename field. The URL field is greyed out per default, but can be activated by activating the radiobutton (checkbox) to the left of the field.
In order to use this feature, users must have the user right upload_by_url, which is granted only to sysops per default. To allow this to normal users, set $wgGroupPermissions['user']['upload_by_url'] = true. Keep in mind that allowing uploads directly from an arbitrary location on the web makes it easier to upload random, unwanted material, and it might be misunderstood as an invitation to upload anything that people might come across on the web.
/*
* Proxy to use for CURL requests.
*/
if ( isset( $_ENV['http_proxy'] )) $wgHTTPProxy = $_ENV['http_proxy'];
[edit] Undeleting images
Undeleting images is possible as an option since MediaWiki 1.8, and enabled by default since MediaWiki 1.11.
Prior to MediaWiki 1.11, you can enable undeletion of images by setting $wgSaveDeletedFiles = true. Since version 1.11, the behavior is controlled by $wgFileStore, and deleted files are per default stored in $wgUploadDirectory/deleted. Since version 1.17, $wgFileStore has been deprecated and $wgDeletedDirectory should be used instead.
[edit] Mass uploading
A number of tools are available for uploading multiple files in one go rather than each file separately:
- Extension:MultiUpload
- Extension:SpecialUploadLocal (1.17+). Requires FTP access.
- Extension:SpecialMultiUploadViaZip
- Commonist (external link to Wiki Commons). Requires file upload via API.PHP.
- with python:
- meta:Uploadmultiple.py
- meta:imageharvest.py copy multiple images to a wiki from a specified URL.
- meta:imagetransfer.py copies images to another wiki
- importImages.php "Place the files on the server in a readable location and execute the maintenance/ importImages.php script from the command line."[8]
- User:Nichalp/Upload script
- Commons:File upload service/Script, deprecated.
- User:File_Upload_Bot_(Kernigh)
[edit] Multiwiki sites
- Make sure you've changed the site location in LocalSettings.php from, e.g. /var/lib/mediawiki to wherever your installation is, and created a writeable images directory (most of the rest can be symlinked). Not doing so will mysteriously break image uploads.
[edit] See also
- Manual:Configuration settings#Uploads for a list of all configuration variables related to file uploads
- Category:Upload variables - similar list as a category (ordered alphabetically)
- You see a blank page when trying to upload a file
[edit] References
- ↑ post-max-size, PHP Core Manual.
- ↑ upload-max-filesize, PHP Core Manual.
- ↑ For an example of where the php.ini file is, see Where is php.ini located?.
- ↑ LimitRequestBody, Apache manual
- ↑ client_max_body_size, Nginx manual
- ↑ server.max-request-size, Lighthttpd manual
- ↑ IIS7 is a new revision (version 7.0) of the Internet Information Services that is part of Windows Vista and the next Windows Server version.
- ↑ http://xpt.sourceforge.net/techdocs/language/wiki/wikimedia/wkm07-MediaWikiImport/index.html#mass_image_upload_zip_
Language: | English • Deutsch • Bahasa Indonesia • 日本語 • Русский • 中文 |
---|