HTTP-Based Object Storages¶
The HTTP-based object storages use an HTTP URL to specify how the object storage is accessed.
The parameters are specified as URL-style parameters, such as http://url/?param1=value1¶m2=value2.
Similarly the URL uses URL escaping, so for example if password is foo/bar
the URL is http://user:foo%2fbar@example.com/.
Additionally, because Dovecot expands %variables inside plugin section, the
% needs to be escaped. So the final string would be e.g.:
plugin {
obox_fs = s3: https://user:foo%%2fbar@example.com/ # password is foo/bar
}
The parameters common to all object storages include:
| Parameter | Description | Default |
|---|---|---|
| absolute_timeout_msecs=<ms> | Maximum total time for an HTTP request to finish. Overrides all timeout configuration | none |
| addhdr=<name>:<value> | Add the specified header to all HTTP requests. This can only be specified once. This may be useful for load balancing | none |
| bucket=<n> | Used by some backends to specify the bucket to save the data into | none |
| bulk_delete=1 | Set to 1 if backend supports bulk deletes | 0 |
| connect_timeout_msecs=<ms> | Timeout for establishing a TCP connection | timeout_msecs |
| delete_max_retries=<n> | Max number of HTTP request retries for delete actions | max_retries |
| delete_timeout_msecs=<ms> | Timeout for sending a delete HTTP response | timeout_msecs |
| max_connect_retries=<n> | Number of connect retries | 2 |
| max_retries=<n> | Max number of HTTP request retries | 4 |
| no_trace_headers=1 | Set to 1 to not add X-Dovecot-User or X-Dovecot-Session headers to HTTP request Useful to correlate object storage requests to AS/Dovecot sessions. If not doing correlations via log aggregation, this is safe to disable. | 0 |
| read_max_retries=<n> | Max number of HTTP request retries for read actions | max_retries |
| read_timeout_msecs=<ms> | Timeout for a receiving reada HTTP response | timeout_msecs |
| reason_header_max_length=<n> | Maximum length for X-Dovecot-Reason HTTP header If header is present, it contains information why obox operation is being done | 0 |
| slow_warn_msecs=<ms> | Log a warning about any HTTP request that takes longer than this many milliseconds | 5s |
| timeout_msecs=<ms> | Default timeout for HTTP responses, unless overwritten by the read/write/delete_timeout_msecs | 10s |
| write_max_retries=<n> | Max number of HTTP request retries for write actions | max_retries |
| write_timeout_msecs=<ms> | Timeout for a write HTTP response | timeout_msecs |
Dovecot sends the following HTTP headers towards storage. They should be logged for troubleshooting purposes:
- X-Dovecot-Username
- X-Dovecot-Session-Id
- X-Dovecot-Reason (v2.2.36.1+ and v2.3.5+)
