configuring_file_upload_limits.diviner

@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`.
    - **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}.