Document configuration of file upload limits

Summary: I have a patch which makes uploads all fancy and adds progress bars, but document the landscape first since it's quite complicated.

Test Plan: Generated, read docs. Configured `storage.upload-size-limit` to various values.

Reviewers: btrahan, vrana

Reviewed By: vrana

CC: aran

Maniphest Tasks: T875

Differential Revision: https://secure.phabricator.com/D2381

src/docs/configuration/configuring_file_storage.diviner

@@ -85,4 +85,6 @@ application (##/file/##) and uploading files.
 
 Continue by:
 
+  - configuring file size upload limits with
+    @{article:Configuring File Upload Limits}; or
   - returning to the @{article:Configuration Guide}.

src/docs/configuration/configuring_file_upload_limits.diviner

@@ -0,0 +1,78 @@
+@title Configuring File Upload Limits
+@group config
+
+Explains limits on file upload sizes.
+
+= Overview =
+
+File uploads are limited by a large number of pieces of configuration, at
+multiple layers of the application. Generally, the minimum value of all the
+limits is the effective one. To upload large files, you need to increase all
+the limits above the maximum file size you want to support. The settings which
+limit uploads are:
+
+  - **HTTP Server**: The HTTP server may set a limit on the maximum request
+    size. If you exceed this limit, you'll see a default server page with an
+    HTTP error. These directives limit the total size of the request body,
+    so they must be somewhat larger than the desired maximum filesize.
+    - **Apache**: Apache limits requests with the Apache `LimitRequestBody`
+      directive.
+    - **nginx**: nginx limits requests with the nginx `client_max_body_size`
+      directive. This often defaults to `1M`.
+    - **lighttpd**: lighttpd limits requests with the lighttpd
+      `server.max-request-size` directive.
+  - **PHP**: PHP has several directives which limit uploads. These directives
+    are found in `php.ini`.
+    - **upload_max_filesize**: Maximum file size PHP will accept in a file
+      upload. If you exceed this, Phabricator will give you a useful error. This
+      often defaults to `2M`.
+    - **post_max_size**: Maximum POST request size PHP will accept. If you
+      exceed this, Phabricator will give you a useful error. This often defaults
+      to `8M`.
+    - **memory_limit**: For some uploads, file data will be read into memory
+      before Phabricator can adjust the memory limit. If you exceed this, PHP
+      may give you a useful error, depending on your configuration.
+    - **max_input_vars**: When files are uploaded via HTML5 drag and drop file
+      upload APIs, PHP parses the file body as though it contained normal POST
+      parameters, and may trigger `max_input_vars` if a file has a lot of
+      brackets in it. You may need to set it to some astronomically high value.
+  - **Storage Engines**: Some storage engines can be configured not to accept
+    files over a certain size. To upload a file, you must have at least one
+    configured storage engine which can accept it. Phabricator should give you
+    useful errors if any of these fail.
+    - **MySQL Engine**: Upload size is limited by the Phabricator setting
+      `storage.mysql-engine.max-size`, which is in turn limited by the MySQL
+      setting `max_allowed_packet`. This often defaults to `1M`.
+    - **Amazon S3**: Upload size is limited by Phabricator's implementation to
+      `5G`.
+    - **Local Disk**: Upload size is limited only by free disk space.
+  - **Resource Constraints**: File uploads are limited by resource constraints
+    on the application server. In particular, some uploaded files are written
+    to disk in their entirety before being moved to storage engines, and all
+    uploaded files are read into memory before being moved. These hard limits
+    should be large for most servers, but will fundamentally prevent Phabricator
+    from processing truly enormous files (GB/TB scale). Phabricator is probably
+    not the best application for this in any case.
+  - **Phabricator Master Limit**: The master limit, `storage.upload-size-limit`,
+    is used to show upload limits in the UI.
+
+Phabricator can't read some of these settings, so it can't figure out what the
+current limit is or be much help at all in configuring it. Thus, you need to
+manually configure all of these limits and then tell Phabricator what you set
+them to. Follow these steps:
+
+  - Pick some limit you want to set, like `100M`.
+  - Configure all of the settings mentioned above to be a bit bigger than the
+    limit you want to enforce (**note that there are some security implications
+    to raising these limits**; principally, your server may become easier to
+    attack with a denial-of-service).
+  - Set `storage.upload-size-limit` to the limit you want.
+  - The UI should now show your limit.
+  - Upload a big file to make sure it works.
+
+= Next Steps =
+
+Continue by:
+
+  - configuring file storage with @{article:Configuring File Storage}; or
+  - retuning to the @{article:Configuration Guide}.