@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
Rewrite file documentation to be chunk-aware
Summary:
Ref T7149. We can simplify configuration somewhat by removing the upload limit setting, now that we support arbitrarily large files.
- Merge configuration documentation.
- Tell users to set things to at least 32MB. This is 8MB maximum one-shot file + 4x headroom. Chunk sizes are 4MB.
Test Plan:
- Faked all the setup warnings.
- Read documentation.
- Uploaded some files.
Reviewers: btrahan
Reviewed By: btrahan
Subscribers: epriestley
Maniphest Tasks: T7149
Differential Revision: https://secure.phabricator.com/D12083
+244
-240
+3
src/applications/config/check/PhabricatorExtraConfigSetupCheck.php
+3
src/applications/config/check/PhabricatorExtraConfigSetupCheck.php
···
214
214
'storage.engine-selector' => pht(
215
215
'Phabricator now automatically discovers available storage engines '.
216
216
'at runtime.'),
217
+
'storage.upload-size-limit' => pht(
218
+
'Phabricator now supports arbitrarily large files. Consult the '.
219
+
'documentation for configuration details.'),
217
220
);
218
221
219
222
return $ancient_config;
+5
-2
src/applications/config/check/PhabricatorMySQLSetupCheck.php
+5
-2
src/applications/config/check/PhabricatorMySQLSetupCheck.php
···
21
21
22
22
protected function executeChecks() {
23
23
$max_allowed_packet = self::loadRawConfigValue('max_allowed_packet');
24
-
$recommended_minimum = 1024 * 1024;
24
+
25
+
// This primarily supports setting the filesize limit for MySQL to 8MB,
26
+
// which may produce a >16MB packet after escaping.
27
+
$recommended_minimum = (32 * 1024 * 1024);
25
28
if ($max_allowed_packet < $recommended_minimum) {
26
29
$message = pht(
27
-
"MySQL is configured with a very small 'max_allowed_packet' (%d), ".
30
+
"MySQL is configured with a small 'max_allowed_packet' (%d), ".
28
31
"which may cause some large writes to fail. Strongly consider raising ".
29
32
"this to at least %d in your MySQL configuration.",
30
33
$max_allowed_packet,
+103
-60
src/applications/config/check/PhabricatorStorageSetupCheck.php
+103
-60
src/applications/config/check/PhabricatorStorageSetupCheck.php
···
10
10
* @phutil-external-symbol class PhabricatorStartup
11
11
*/
12
12
protected function executeChecks() {
13
-
$upload_limit = PhabricatorEnv::getEnvConfig('storage.upload-size-limit');
14
-
if (!$upload_limit) {
13
+
$chunk_engine_active = false;
14
+
15
+
$engines = PhabricatorFileStorageEngine::loadWritableEngines();
16
+
foreach ($engines as $engine) {
17
+
if ($engine->isChunkEngine()) {
18
+
$chunk_engine_active = true;
19
+
break;
20
+
}
21
+
}
22
+
23
+
if (!$chunk_engine_active) {
24
+
$doc_href = PhabricatorEnv::getDocLink('Configuring File Storage');
25
+
15
26
$message = pht(
16
-
'The Phabricator file upload limit is not configured. You may only '.
17
-
'be able to upload very small files until you configure it, because '.
18
-
'some PHP default limits are very low (as low as 2MB).');
27
+
'Large file storage has not been configured, which will limit '.
28
+
'the maximum size of file uploads. See %s for '.
29
+
'instructions on configuring uploads and storage.',
30
+
phutil_tag(
31
+
'a',
32
+
array(
33
+
'href' => $doc_href,
34
+
'target' => '_blank',
35
+
),
36
+
pht('Configuring File Storage')));
19
37
20
38
$this
21
-
->newIssue('config.storage.upload-size-limit')
22
-
->setShortName(pht('Upload Limit'))
23
-
->setName(pht('Upload Limit Not Yet Configured'))
24
-
->setMessage($message)
25
-
->addPhabricatorConfig('storage.upload-size-limit');
26
-
} else {
27
-
$memory_limit = PhabricatorStartup::getOldMemoryLimit();
28
-
if ($memory_limit && ((int)$memory_limit > 0)) {
29
-
$memory_limit_bytes = phutil_parse_bytes($memory_limit);
30
-
$memory_usage_bytes = memory_get_usage();
31
-
$upload_limit_bytes = phutil_parse_bytes($upload_limit);
39
+
->newIssue('large-files')
40
+
->setShortName(pht('Large Files'))
41
+
->setName(pht('Large File Storage Not Configured'))
42
+
->setMessage($message);
43
+
}
32
44
33
-
$available_bytes = ($memory_limit_bytes - $memory_usage_bytes);
45
+
$post_max_size = ini_get('post_max_size');
46
+
if ($post_max_size && ((int)$post_max_size > 0)) {
47
+
$post_max_bytes = phutil_parse_bytes($post_max_size);
48
+
$post_max_need = (32 * 1024 * 1024) * 100;
49
+
if ($post_max_need > $post_max_bytes) {
50
+
$summary = pht(
51
+
'Set %s in your PHP configuration to at least 32MB '.
52
+
'to support large file uploads.',
53
+
phutil_tag('tt', array(), 'post_max_size'));
54
+
55
+
$message = pht(
56
+
'Adjust %s in your PHP configuration to at least 32MB. When '.
57
+
'set to smaller value, large file uploads may not work properly.',
58
+
phutil_tag('tt', array(), 'post_max_size'));
59
+
60
+
$this
61
+
->newIssue('php.post_max_size')
62
+
->setName(pht('PHP post_max_size Not Configured'))
63
+
->setSummary($summary)
64
+
->setMessage($message)
65
+
->setGroup(self::GROUP_PHP)
66
+
->addPHPConfig('post_max_size');
67
+
}
68
+
}
69
+
70
+
// This is somewhat arbitrary, but make sure we have enough headroom to
71
+
// upload a default file at the chunk threshold (8MB), which may be
72
+
// base64 encoded, then JSON encoded in the request, and may need to be
73
+
// held in memory in the raw and as a query string.
74
+
$need_bytes = (64 * 1024 * 1024);
75
+
76
+
$memory_limit = PhabricatorStartup::getOldMemoryLimit();
77
+
if ($memory_limit && ((int)$memory_limit > 0)) {
78
+
$memory_limit_bytes = phutil_parse_bytes($memory_limit);
79
+
$memory_usage_bytes = memory_get_usage();
80
+
81
+
$available_bytes = ($memory_limit_bytes - $memory_usage_bytes);
34
82
35
-
if ($upload_limit_bytes > $available_bytes) {
36
-
$summary = pht(
37
-
'Your PHP memory limit is configured in a way that may prevent '.
38
-
'you from uploading large files.');
83
+
if ($need_bytes > $available_bytes) {
84
+
$summary = pht(
85
+
'Your PHP memory limit is configured in a way that may prevent '.
86
+
'you from uploading large files or handling large requests.');
39
87
40
-
$message = pht(
41
-
'When you upload a file via drag-and-drop or the API, the entire '.
42
-
'file is buffered into memory before being written to permanent '.
43
-
'storage. Phabricator needs memory available to store these '.
44
-
'files while they are uploaded, but PHP is currently configured '.
45
-
'to limit the available memory.'.
46
-
"\n\n".
47
-
'Your Phabricator %s is currently set to a larger value (%s) than '.
48
-
'the amount of available memory (%s) that a PHP process has '.
49
-
'available to use, so uploads via drag-and-drop and the API will '.
50
-
'hit the memory limit before they hit other limits.'.
51
-
"\n\n".
52
-
'(Note that the application itself must also fit in available '.
53
-
'memory, so not all of the memory under the memory limit is '.
54
-
'available for buffering file uploads.)'.
55
-
"\n\n".
56
-
"The easiest way to resolve this issue is to set %s to %s in your ".
57
-
"PHP configuration, to disable the memory limit. There is ".
58
-
"usually little or no value to using this option to limit ".
59
-
"Phabricator process memory.".
60
-
"\n\n".
61
-
"You can also increase the limit, or decrease %s, or ignore this ".
62
-
"issue and accept that these upload mechanisms will be limited ".
63
-
"in the size of files they can handle.",
64
-
phutil_tag('tt', array(), 'storage.upload-size-limit'),
65
-
phutil_format_bytes($upload_limit_bytes),
66
-
phutil_format_bytes($available_bytes),
67
-
phutil_tag('tt', array(), 'memory_limit'),
68
-
phutil_tag('tt', array(), '-1'),
69
-
phutil_tag('tt', array(), 'storage.upload-size-limit'));
88
+
$message = pht(
89
+
'When you upload a file via drag-and-drop or the API, chunks must '.
90
+
'be buffered into memory before being written to permanent '.
91
+
'storage. Phabricator needs memory available to store these '.
92
+
'chunks while they are uploaded, but PHP is currently configured '.
93
+
'to severly limit the available memory.'.
94
+
"\n\n".
95
+
'PHP processes currently have very little free memory available '.
96
+
'(%s). To work well, processes should have at least %s.'.
97
+
"\n\n".
98
+
'(Note that the application itself must also fit in available '.
99
+
'memory, so not all of the memory under the memory limit is '.
100
+
'available for running workloads.)'.
101
+
"\n\n".
102
+
"The easiest way to resolve this issue is to set %s to %s in your ".
103
+
"PHP configuration, to disable the memory limit. There is ".
104
+
"usually little or no value to using this option to limit ".
105
+
"Phabricator process memory.".
106
+
"\n\n".
107
+
"You can also increase the limit or ignore this issue and accept ".
108
+
"that you may encounter problems uploading large files and ".
109
+
"processing large requests.",
110
+
phutil_format_bytes($available_bytes),
111
+
phutil_format_bytes($need_bytes),
112
+
phutil_tag('tt', array(), 'memory_limit'),
113
+
phutil_tag('tt', array(), '-1'));
70
114
71
-
$this
72
-
->newIssue('php.memory_limit.upload')
73
-
->setName(pht('Memory Limit Restricts File Uploads'))
74
-
->setSummary($summary)
75
-
->setMessage($message)
76
-
->addPHPConfig('memory_limit')
77
-
->addPHPConfigOriginalValue('memory_limit', $memory_limit)
78
-
->addPhabricatorConfig('storage.upload-size-limit');
79
-
}
115
+
$this
116
+
->newIssue('php.memory_limit.upload')
117
+
->setName(pht('Memory Limit Restricts File Uploads'))
118
+
->setSummary($summary)
119
+
->setMessage($message)
120
+
->setGroup(self::GROUP_PHP)
121
+
->addPHPConfig('memory_limit')
122
+
->addPHPConfigOriginalValue('memory_limit', $memory_limit);
80
123
}
81
124
}
82
125
-20
src/applications/files/config/PhabricatorFilesConfigOptions.php
-20
src/applications/files/config/PhabricatorFilesConfigOptions.php
···
147
147
"Set this to a valid Amazon S3 bucket to store files there. You ".
148
148
"must also configure S3 access keys in the 'Amazon Web Services' ".
149
149
"group.")),
150
-
$this->newOption('storage.upload-size-limit', 'string', null)
151
-
->setSummary(
152
-
pht('Limit to users in interfaces which allow uploading.'))
153
-
->setDescription(
154
-
pht(
155
-
"Set the size of the largest file a user may upload. This is ".
156
-
"used to render text like 'Maximum file size: 10MB' on ".
157
-
"interfaces where users can upload files, and files larger than ".
158
-
"this size will be rejected. \n\n".
159
-
"NOTE: **Setting this to a large size is NOT sufficient to ".
160
-
"allow users to upload large files. You must also configure a ".
161
-
"number of other settings.** To configure file upload limits, ".
162
-
"consult the article 'Configuring File Upload Limits' in the ".
163
-
"documentation. Once you've configured some limit across all ".
164
-
"levels of the server, you can set this limit to an appropriate ".
165
-
"value and the UI will then reflect the actual configured ".
166
-
"limit.\n\n".
167
-
"Specify this limit in bytes, or using a 'K', 'M', or 'G' ".
168
-
"suffix."))
169
-
->addExample('10M', pht('Allow Uploads 10MB or Smaller')),
170
150
$this->newOption(
171
151
'metamta.files.public-create-email',
172
152
'string',
+1
-23
src/applications/files/controller/PhabricatorFileUploadController.php
+1
-23
src/applications/files/controller/PhabricatorFileUploadController.php
···
57
57
id(new AphrontFormFileControl())
58
58
->setLabel(pht('File'))
59
59
->setName('file')
60
-
->setError($e_file)
61
-
->setCaption($this->renderUploadLimit()))
60
+
->setError($e_file))
62
61
->appendChild(
63
62
id(new AphrontFormTextControl())
64
63
->setLabel(pht('Name'))
···
100
99
array(
101
100
'title' => $title,
102
101
));
103
-
}
104
-
105
-
private function renderUploadLimit() {
106
-
$limit = PhabricatorEnv::getEnvConfig('storage.upload-size-limit');
107
-
$limit = phutil_parse_bytes($limit);
108
-
if ($limit) {
109
-
$formatted = phutil_format_bytes($limit);
110
-
return 'Maximum file size: '.$formatted;
111
-
}
112
-
113
-
$doc_href = PhabricatorEnv::getDocLink(
114
-
'Configuring File Upload Limits');
115
-
$doc_link = phutil_tag(
116
-
'a',
117
-
array(
118
-
'href' => $doc_href,
119
-
'target' => '_blank',
120
-
),
121
-
'Configuring File Upload Limits');
122
-
123
-
return hsprintf('Upload limit is not configured, see %s.', $doc_link);
124
102
}
125
103
126
104
}
-5
src/applications/files/exception/PhabricatorFileUploadException.php
-5
src/applications/files/exception/PhabricatorFileUploadException.php
···
20
20
'Unable to write file: failed to write to temporary directory.',
21
21
UPLOAD_ERR_EXTENSION =>
22
22
'Unable to upload: a PHP extension stopped the upload.',
23
-
24
-
-1000 =>
25
-
pht("Uploaded file is too large: current limit is %s. To adjust this ".
26
-
"limit change 'storage.upload-size-limit' in the Phabricator config.",
27
-
PhabricatorEnv::getEnvConfig('storage.upload-size-limit')),
28
23
);
29
24
30
25
$message = idx($map, $code, 'Upload failed: unknown error.');
-15
src/applications/files/storage/PhabricatorFile.php
-15
src/applications/files/storage/PhabricatorFile.php
···
162
162
throw new Exception('File size disagrees with uploaded size.');
163
163
}
164
164
165
-
self::validateFileSize(strlen($file_data));
166
-
167
165
return $file_data;
168
166
}
169
167
···
181
179
}
182
180
183
181
public static function newFromXHRUpload($data, array $params = array()) {
184
-
self::validateFileSize(strlen($data));
185
182
return self::newFromFileData($data, $params);
186
-
}
187
-
188
-
private static function validateFileSize($size) {
189
-
$limit = PhabricatorEnv::getEnvConfig('storage.upload-size-limit');
190
-
if (!$limit) {
191
-
return;
192
-
}
193
-
194
-
$limit = phutil_parse_bytes($limit);
195
-
if ($size > $limit) {
196
-
throw new PhabricatorFileUploadException(-1000);
197
-
}
198
183
}
199
184
200
185
+132
-38
src/docs/user/configuration/configuring_file_storage.diviner
+132
-38
src/docs/user/configuration/configuring_file_storage.diviner
···
1
1
@title Configuring File Storage
2
2
@group config
3
3
4
-
Setup how Phabricator will store files.
4
+
Setup file storage and support for large files.
5
5
6
6
Overview
7
7
========
8
8
9
-
Phabricator allows users to upload files, and several applications use file
10
-
storage (for instance, Maniphest allows you to attach files to tasks). You can
11
-
configure several different storage systems.
9
+
This document describes how to configure Phabricator to support large file
10
+
uploads, and how to choose where Phabricator stores files.
11
+
12
+
There are two major things to configure:
13
+
14
+
- set up PHP and your HTTP server to accept large requests;
15
+
- choose and configure a storage engine.
16
+
17
+
The following sections will guide you through this configuration.
18
+
19
+
20
+
How Phabricator Stores Files
21
+
============================
22
+
23
+
Phabricator stores files in "storage engines", which are modular backends
24
+
that implement access to some storage system (like MySQL, the filesystem, or
25
+
a cloud storage service like Amazon S3).
26
+
27
+
Phabricator stores large files by breaking them up into many chunks (a few
28
+
megabytes in size) and storing the chunks in an underlying storage engine.
29
+
This makes it easier to implement new storage engines and gives Phabricator
30
+
more flexibility in managing file data.
31
+
32
+
The first section of this document discusses configuring your install so that
33
+
PHP and your HTTP server will accept requests which are larger than the size of
34
+
one file chunk. Without this configuration, file chunk data will be rejected.
35
+
36
+
The second section discusses choosing and configuring storage engines, so data
37
+
is stored where you want it to be.
38
+
39
+
40
+
Configuring Upload Limits
41
+
=========================
42
+
43
+
File uploads are limited by several pieces of configuration at different layers
44
+
of the stack. Generally, the minimum value of all the limits is the effective
45
+
one.
46
+
47
+
To upload large files, you need to increase all the limits to at least
48
+
**32MB**. This will allow you to upload file chunks, which will let Phabricator
49
+
store arbitrarily large files.
50
+
51
+
The settings which limit file uploads are:
52
+
53
+
**HTTP Server**: The HTTP server may set a limit on the maximum request size.
54
+
If you exceed this limit, you'll see a default server page with an HTTP error.
55
+
These directives limit the total size of the request body, so they must be
56
+
somewhat larger than the desired maximum filesize.
57
+
58
+
- **Apache**: Apache limits requests with the Apache `LimitRequestBody`
59
+
directive.
60
+
- **nginx**: nginx limits requests with the nginx `client_max_body_size`
61
+
directive. This often defaults to `1M`.
62
+
- **lighttpd**: lighttpd limits requests with the lighttpd
63
+
`server.max-request-size` directive.
12
64
13
-
| System | Setup | Cost | Notes |
65
+
Set the applicable limit to at least **32MB**. Phabricator can not read these
66
+
settings, so it can not raise setup warnings if they are misconfigured.
67
+
68
+
**PHP**: PHP has several directives which limit uploads. These directives are
69
+
found in `php.ini`.
70
+
71
+
- **post_max_size**: Maximum POST request size PHP will accept. If you
72
+
exceed this, Phabricator will give you a useful error. This often defaults
73
+
to `8M`. Set this to at least `32MB`. Phabricator will give you a setup
74
+
warning about this if it is set too low.
75
+
- **memory_limit**: For some uploads, file data will be read into memory
76
+
before Phabricator can adjust the memory limit. If you exceed this, PHP
77
+
may give you a useful error, depending on your configuration. It is
78
+
recommended that you set this to `-1` to disable it. Phabricator will
79
+
give you a setup warning about this if it is set too low.
80
+
81
+
You may also want to configure these PHP options:
82
+
83
+
- **max_input_vars**: When files are uploaded via HTML5 drag and drop file
84
+
upload APIs, PHP parses the file body as though it contained normal POST
85
+
parameters, and may trigger `max_input_vars` if a file has a lot of
86
+
brackets in it. You may need to set it to some astronomically high value.
87
+
- **upload_max_filesize**: Maximum file size PHP will accept in a raw file
88
+
upload. This is not normally used when uploading files via drag-and-drop,
89
+
but affects some other kinds of file uploads. If you exceed this,
90
+
Phabricator will give you a useful error. This often defaults to `2M`. Set
91
+
this to at least `32MB`.
92
+
93
+
Once you've adjusted all this configuration, your server will be able to
94
+
receive chunk uploads. As long as you have somewhere to store them, this will
95
+
enable you to store arbitrarily large files.
96
+
97
+
98
+
Storage Engines
99
+
===============
100
+
101
+
Phabricator supports several different file storage engines:
102
+
103
+
| Engine | Setup | Cost | Notes |
14
104
|========|=======|======|=======|
15
105
| MySQL | Automatic | Free | May not scale well. |
16
106
| Local Disk | Easy | Free | Does not scale well. |
17
107
| Amazon S3 | Easy | Cheap | Scales well. |
18
108
| Custom | Hard | Varies | Implement a custom storage engine. |
19
109
110
+
You can review available storage engines and their configuration by navigating
111
+
to {nav Applications > Files > Help/Options > Storage Engines} in the web UI.
112
+
20
113
By default, Phabricator is configured to store files up to 1MB in MySQL, and
21
114
reject files larger than 1MB. To store larger files, you can either:
22
115
23
-
- configure local disk storage; or
24
-
- configure Amazon S3 storage; or
25
-
- raise the limits on MySQL.
116
+
- increase the MySQL limit to at least 8MB; or
117
+
- configure another storage engine.
26
118
27
-
See the rest of this document for some additional discussion of engines.
119
+
Doing either of these will enable the chunk storage engine and support for
120
+
arbitrarily large files.
28
121
29
-
You don't have to fully configure this immediately, the defaults are okay until
30
-
you need to upload larger files and it's relatively easy to port files between
31
-
storage engines later.
122
+
The remaining sections of this document discuss the available storage engines
123
+
and how to configure them.
32
124
33
-
Storage Engines
34
-
===============
35
125
36
-
Builtin storage engines and information on how to configure them.
126
+
Engine: MySQL
127
+
=============
37
128
38
-
== MySQL ==
39
-
40
-
- **Pros**: Fast, no setup required.
41
-
- **Cons**: Storing files in a database is a classic bad idea. Does not scale
42
-
well. Maximum file size is limited.
129
+
- **Pros**: Low latency, no setup required.
130
+
- **Cons**: Storing files in a database is a classic bad idea. May become
131
+
difficult to administrate if you have a large amount of data.
43
132
44
133
MySQL storage is configured by default, for files up to (just under) 1MB. You
45
134
can configure it with these keys:
···
49
138
50
139
For most installs, it is reasonable to leave this engine as-is and let small
51
140
files (like thumbnails and profile images) be stored in MySQL, which is usually
52
-
the lowest-latency filestore.
141
+
the lowest-latency filestore, even if you configure another storage engine.
53
142
54
-
To support larger files, configure another engine or increase this limit.
143
+
To support large files, increase this limit to at least **8MB**. This will
144
+
activate chunk storage in MySQL.
55
145
56
-
== Local Disk ==
146
+
Engine: Local Disk
147
+
==================
57
148
58
-
- **Pros**: Very simple. Almost no setup required.
149
+
- **Pros**: Simple to setup.
59
150
- **Cons**: Doesn't scale to multiple web frontends without NFS.
60
151
61
-
To upload larger files:
152
+
To configure file storage on the local disk, set:
62
153
63
154
- `storage.local-disk.path`: Set to some writable directory on local disk.
64
155
Make that directory.
65
156
66
-
== Amazon S3 ==
157
+
Engine: Amazon S3
158
+
=================
67
159
68
160
- **Pros**: Scales well.
69
-
- **Cons**: More complicated and expensive than other approaches.
161
+
- **Cons**: Slightly more complicated than other engines, not free.
70
162
71
-
To enable file storage in S3, set these key:
163
+
To enable file storage in S3, set these keys:
72
164
73
-
- ##amazon-s3.access-key## Your AWS access key.
74
-
- ##amazon-s3.secret-key## Your AWS secret key.
75
-
- ##storage.s3.bucket## S3 bucket name where files should be stored.
165
+
- `amazon-s3.access-key`: Your AWS access key.
166
+
- `amazon-s3.secret-key`: Your AWS secret key.
167
+
- `storage.s3.bucket`: S3 bucket name where files should be stored.
76
168
77
-
= Testing Storage Engines =
169
+
Testing Storage Engines
170
+
=======================
78
171
79
-
You can test that things are correctly configured by going to the Files
80
-
application (##/file/##) and uploading files.
172
+
You can test that things are correctly configured by dragging and dropping
173
+
a file onto the Phabricator home page. If engines have been configured
174
+
properly, the file should upload.
81
175
82
-
= Migrating Files Between Engines =
176
+
Migrating Files Between Engines
177
+
===============================
83
178
84
179
If you want to move files between storage engines, you can use the `bin/files`
85
180
script to perform migrations. For example, suppose you previously used MySQL but
···
95
190
You can use `--dry-run` to show which migrations would be performed without
96
191
taking any action. Run `bin/files help` for more options and information.
97
192
98
-
= Next Steps =
193
+
Next Steps
194
+
==========
99
195
100
196
Continue by:
101
197
102
-
- configuring file size upload limits with
103
-
@{article:Configuring File Upload Limits}; or
104
198
- returning to the @{article:Configuration Guide}.
-77
src/docs/user/configuration/configuring_file_upload_limits.diviner
-77
src/docs/user/configuration/configuring_file_upload_limits.diviner
···
1
-
@title Configuring File Upload Limits
2
-
@group config
3
-
4
-
Explains limits on file upload sizes.
5
-
6
-
= Overview =
7
-
8
-
File uploads are limited by a large number of pieces of configuration, at
9
-
multiple layers of the application. Generally, the minimum value of all the
10
-
limits is the effective one. To upload large files, you need to increase all
11
-
the limits above the maximum file size you want to support. The settings which
12
-
limit uploads are:
13
-
14
-
- **HTTP Server**: The HTTP server may set a limit on the maximum request
15
-
size. If you exceed this limit, you'll see a default server page with an
16
-
HTTP error. These directives limit the total size of the request body,
17
-
so they must be somewhat larger than the desired maximum filesize.
18
-
- **Apache**: Apache limits requests with the Apache `LimitRequestBody`
19
-
directive.
20
-
- **nginx**: nginx limits requests with the nginx `client_max_body_size`
21
-
directive. This often defaults to `1M`.
22
-
- **lighttpd**: lighttpd limits requests with the lighttpd
23
-
`server.max-request-size` directive.
24
-
- **PHP**: PHP has several directives which limit uploads. These directives
25
-
are found in `php.ini`.
26
-
- **upload_max_filesize**: Maximum file size PHP will accept in a file
27
-
upload. If you exceed this, Phabricator will give you a useful error. This
28
-
often defaults to `2M`.
29
-
- **post_max_size**: Maximum POST request size PHP will accept. If you
30
-
exceed this, Phabricator will give you a useful error. This often defaults
31
-
to `8M`.
32
-
- **memory_limit**: For some uploads, file data will be read into memory
33
-
before Phabricator can adjust the memory limit. If you exceed this, PHP
34
-
may give you a useful error, depending on your configuration.
35
-
- **max_input_vars**: When files are uploaded via HTML5 drag and drop file
36
-
upload APIs, PHP parses the file body as though it contained normal POST
37
-
parameters, and may trigger `max_input_vars` if a file has a lot of
38
-
brackets in it. You may need to set it to some astronomically high value.
39
-
- **Storage Engines**: Some storage engines can be configured not to accept
40
-
files over a certain size. To upload a file, you must have at least one
41
-
configured storage engine which can accept it. Phabricator should give you
42
-
useful errors if any of these fail.
43
-
- **MySQL Engine**: Upload size is limited by the Phabricator setting
44
-
`storage.mysql-engine.max-size`.
45
-
- **Amazon S3**: Upload size is limited by Phabricator's implementation to
46
-
`5G`.
47
-
- **Local Disk**: Upload size is limited only by free disk space.
48
-
- **Resource Constraints**: File uploads are limited by resource constraints
49
-
on the application server. In particular, some uploaded files are written
50
-
to disk in their entirety before being moved to storage engines, and all
51
-
uploaded files are read into memory before being moved. These hard limits
52
-
should be large for most servers, but will fundamentally prevent Phabricator
53
-
from processing truly enormous files (GB/TB scale). Phabricator is probably
54
-
not the best application for this in any case.
55
-
- **Phabricator Master Limit**: The master limit, `storage.upload-size-limit`,
56
-
is used to show upload limits in the UI.
57
-
58
-
Phabricator can't read some of these settings, so it can't figure out what the
59
-
current limit is or be much help at all in configuring it. Thus, you need to
60
-
manually configure all of these limits and then tell Phabricator what you set
61
-
them to. Follow these steps:
62
-
63
-
- Pick some limit you want to set, like `100M`.
64
-
- Configure all of the settings mentioned above to be a bit bigger than the
65
-
limit you want to enforce (**note that there are some security implications
66
-
to raising these limits**; principally, your server may become easier to
67
-
attack with a denial-of-service).
68
-
- Set `storage.upload-size-limit` to the limit you want.
69
-
- The UI should now show your limit.
70
-
- Upload a big file to make sure it works.
71
-
72
-
= Next Steps =
73
-
74
-
Continue by:
75
-
76
-
- configuring file storage with @{article:Configuring File Storage}; or
77
-
- returning to the @{article:Configuration Guide}.