1# ngx_brotli 2 3Brotli is a generic-purpose lossless compression algorithm that compresses data 4using a combination of a modern variant of the LZ77 algorithm, Huffman coding 5and 2nd order context modeling, with a compression ratio comparable to the best 6currently available general-purpose compression methods. It is similar in speed 7with deflate but offers more dense compression. 8 9ngx_brotli is a set of two nginx modules: 10 11- ngx_brotli filter module - used to compress responses on-the-fly, 12- ngx_brotli static module - used to serve pre-compressed files. 13 14[![TravisCI Build Status](https://travis-ci.org/google/ngx_brotli.svg?branch=master)](https://travis-ci.org/google/ngx_brotli) 15 16## Table of Contents 17 18- [Status](#status) 19- [Installation](#installation) 20- [Configuration directives](#configuration-directives) 21 - [`brotli_static`](#brotli_static) 22 - [`brotli`](#brotli) 23 - [`brotli_types`](#brotli_types) 24 - [`brotli_buffers`](#brotli_buffers) 25 - [`brotli_comp_level`](#brotli_comp_level) 26 - [`brotli_window`](#brotli_window) 27 - [`brotli_min_length`](#brotli_min_length) 28- [Variables](#variables) 29 - [`$brotli_ratio`](#brotli_ratio) 30- [Sample configuration](#sample-configuration) 31- [Contributing](#contributing) 32- [License](#license) 33 34## Status 35 36Both Brotli library and nginx module are under active development. 37 38## Installation 39 40### Dynamically loaded 41 42 $ cd nginx-1.x.x 43 $ ./configure --with-compat --add-dynamic-module=/path/to/ngx_brotli 44 $ make modules 45 46You will need to use **exactly** the same `./configure` arguments as your Nginx configuration and append `--with-compat --add-dynamic-module=/path/to/ngx_brotli` to the end, otherwise you will get a "module is not binary compatible" error on startup. You can run `nginx -V` to get the configuration arguments for your Nginx installation. 47 48`make modules` will result in `ngx_http_brotli_filter_module.so` and `ngx_http_brotli_static_module.so` in the `objs` directory. Copy these to `/usr/lib/nginx/modules/` then add the `load_module` directives to `nginx.conf` (above the http block): 49```nginx 50load_module modules/ngx_http_brotli_filter_module.so; 51load_module modules/ngx_http_brotli_static_module.so; 52``` 53 54### Statically compiled 55 56 $ cd nginx-1.x.x 57 $ ./configure --add-module=/path/to/ngx_brotli 58 $ make && make install 59 60This will compile the module directly into Nginx. 61 62## Configuration directives 63 64### `brotli_static` 65 66- **syntax**: `brotli_static on|off|always` 67- **default**: `off` 68- **context**: `http`, `server`, `location` 69 70Enables or disables checking of the existence of pre-compressed files with`.br` 71extension. With the `always` value, pre-compressed file is used in all cases, 72without checking if the client supports it. 73 74### `brotli` 75 76- **syntax**: `brotli on|off` 77- **default**: `off` 78- **context**: `http`, `server`, `location`, `if` 79 80Enables or disables on-the-fly compression of responses. 81 82### `brotli_types` 83 84- **syntax**: `brotli_types <mime_type> [..]` 85- **default**: `text/html` 86- **context**: `http`, `server`, `location` 87 88Enables on-the-fly compression of responses for the specified MIME types 89in addition to `text/html`. The special value `*` matches any MIME type. 90Responses with the `text/html` MIME type are always compressed. 91 92### `brotli_buffers` 93 94- **syntax**: `brotli_buffers <number> <size>` 95- **default**: `32 4k|16 8k` 96- **context**: `http`, `server`, `location` 97 98**Deprecated**, ignored. 99 100### `brotli_comp_level` 101 102- **syntax**: `brotli_comp_level <level>` 103- **default**: `6` 104- **context**: `http`, `server`, `location` 105 106Sets on-the-fly compression Brotli quality (compression) `level`. 107Acceptable values are in the range from `0` to `11`. 108 109### `brotli_window` 110 111- **syntax**: `brotli_window <size>` 112- **default**: `512k` 113- **context**: `http`, `server`, `location` 114 115Sets Brotli window `size`. Acceptable values are `1k`, `2k`, `4k`, `8k`, `16k`, 116`32k`, `64k`, `128k`, `256k`, `512k`, `1m`, `2m`, `4m`, `8m` and `16m`. 117 118### `brotli_min_length` 119 120- **syntax**: `brotli_min_length <length>` 121- **default**: `20` 122- **context**: `http`, `server`, `location` 123 124Sets the minimum `length` of a response that will be compressed. 125The length is determined only from the `Content-Length` response header field. 126 127## Variables 128 129### `$brotli_ratio` 130 131Achieved compression ratio, computed as the ratio between the original 132and compressed response sizes. 133 134## Sample configuration 135 136``` 137brotli on; 138brotli_comp_level 6; 139brotli_static on; 140brotli_types application/atom+xml application/javascript application/json application/rss+xml 141 application/vnd.ms-fontobject application/x-font-opentype application/x-font-truetype 142 application/x-font-ttf application/x-javascript application/xhtml+xml application/xml 143 font/eot font/opentype font/otf font/truetype image/svg+xml image/vnd.microsoft.icon 144 image/x-icon image/x-win-bitmap text/css text/javascript text/plain text/xml; 145``` 146 147## Contributing 148 149See [Contributing](CONTRIBUTING.md). 150 151## License 152 153 Copyright (C) 2002-2015 Igor Sysoev 154 Copyright (C) 2011-2015 Nginx, Inc. 155 Copyright (C) 2015 Google Inc. 156 All rights reserved. 157 158 Redistribution and use in source and binary forms, with or without 159 modification, are permitted provided that the following conditions 160 are met: 161 1. Redistributions of source code must retain the above copyright 162 notice, this list of conditions and the following disclaimer. 163 2. Redistributions in binary form must reproduce the above copyright 164 notice, this list of conditions and the following disclaimer in the 165 documentation and/or other materials provided with the distribution. 166 167 THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 168 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 169 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 170 ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 171 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 172 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 173 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 174 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 175 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 176 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 177 SUCH DAMAGE. 178