diff --git a/doc/configuration.txt b/doc/configuration.txt index c1b6d74ddb..ea326d19a7 100644 --- a/doc/configuration.txt +++ b/doc/configuration.txt @@ -108,6 +108,7 @@ Summary 9.2. HTTP compression 9.3. Stream Processing Offload Engine (SPOE) +10. Cache 1. Quick reminder about HTTP ---------------------------- @@ -3877,7 +3878,8 @@ http-request { allow | auth [realm ] | redirect | reject | sc-inc-gpc0() | sc-set-gpt0() | silent-drop | - send-spoe-group + send-spoe-group | + cache-use } [ { if | unless } ] Access control for Layer 7 requests @@ -4112,6 +4114,9 @@ http-request { allow | auth [realm ] | redirect | reject | If the slot doesn't exist, then HAProxy fails parsing the configuration to prevent unexpected behavior at run time. + - cache-use : + See section 10.2 about cache setup. + - { track-sc0 | track-sc1 | track-sc2 } [table ] : enables tracking of sticky counters from current request. These rules do not stop evaluation and do not change default action. Three sets of @@ -4373,7 +4378,8 @@ http-response { allow | deny | add-header | set-nice | sc-inc-gpc0() | sc-set-gpt0() | silent-drop | - send-spoe-group + send-spoe-group | + cache-store } [ { if | unless } ] Access control for Layer 7 responses @@ -4550,6 +4556,9 @@ http-response { allow | deny | add-header | set-nice | If the slot doesn't exist, then HAProxy fails parsing the configuration to prevent unexpected behavior at run time. + - cache-store : + See section 10.2 about cache setup. + - "redirect" : this performs an HTTP redirection based on a redirect rule. This supports a format string similarly to "http-request redirect" rules, with the exception that only the "location" type of redirect is possible @@ -16938,6 +16947,101 @@ Important note: The SPOE filter is highly experimental for now and was not heavily tested. It is really not production ready. So use it carefully. +10. Cache +--------- + +HAProxy provides a cache, which was designed to perform cache on small objects +(favicon, css...). This is a minimalist low-maintenance cache which runs in +RAM. + +The cache is based on a memory which is shared between processes and threads, +this memory is splitted in blocks of 1k. + +If an object is not used anymore, it can be deleted to store a new object +independently of its expiration date. The oldest objects are deleted first +when we try to allocate a new one. + +The cache use a hash of the host header and the URI as the key. + +It's possible to view the status of a cache using the Unix socket command +"show cache" consult section 9.3 "Unix Socket commands" of Management Guide +for more details. + +When an object is delivered from the cache, the server name in the log is +replaced by "". + +10.1 Limitation +--------------- + +The cache won't store and won't deliver objects in these cases: + +- If the response is not a 200 +- If the response contains a Vary header +- If the response does not contain a Content-Length header or if the + Content-Length + the headers size is greater than a buffer size - the + reserve. +- If the response is not cacheable + +- If the request is not a GET +- If the HTTP version of the request is smaller than 1.1 + +Caution!: Due to the current limitation of the filters, it is not recommended +to use the cache with other filters. Using them can cause undefined behavior +if they modify the response (compression for exemple). + +10.2 Setup +---------- + +To setup a cache, you must define a cache section and use it in a proxy with +the corresponding http-request and response actions. + +10.2.1 Cache section +-------------------- + +cache + Declare a cache section, allocate a shared cache memory named , the + size of cache is mandatory. + +total-max-size + Define the size in RAM of the cache in megabytes. this size is splitted in + blocks of 1kb which are used by the cache entries. + +max-age + Define the maximum expiration duration. The expiration is set has the lowest + value between the s-maxage or max-age (in this order) directive in the + Cache-Control response header and this value. The default value is 60 + seconds, which means that you can't cache an object more than 60 seconds by + default. + +10.2.2 Proxy section +-------------------- + +http-request cache-use + Try to deliver a cached object from the cache . This directive is also + mandatory to store the cache as it calculates the cache hash. If you want to + use a condition for both storage and delivering that's a good idea to put it + after this one. + +http-response cache-store + Store an http-response within the cache. The storage of the response headers + is done at this step, which means you can use others http-response actions + to modify headers before or after the storage of the response. This action + is responsible for the setup of the cache storage filter. + + +Example: + + backend bck1 + mode http + + http-request cache-use foobar + http-response cache-store foobar + server srv1 127.0.0.1:80 + + cache foobar + total-max-size 4 + max-age 240 + /* * Local variables: * fill-column: 79 diff --git a/doc/management.txt b/doc/management.txt index 6fb255ad75..86ad048c63 100644 --- a/doc/management.txt +++ b/doc/management.txt @@ -1754,6 +1754,28 @@ show cli sockets 127.0.0.2:9969 user 2 [::1]:9999 operator 2 +show cache + List the configurated caches and the objects stored in each cache tree. + + $ echo 'show cache' | socat stdio /tmp/sock1 + 0x7f6ac6c5b03a: foobar (shctx:0x7f6ac6c5b000, available blocks:3918) + 1 2 3 4 + + 1. pointer to the cache structure + 2. cache name + 3. pointer to the mmap area (shctx) + 4. number of blocks available for reuse in the shctx + + 0x7f6ac6c5b4cc hash:286881868 size:39114 (39 blocks), refcount:9, expire:237 + 1 2 3 4 5 6 + + 1. pointer to the cache entry + 2. first 32 bits of the hash + 3. size of the object in bytes + 4. number of blocks used for the object + 5. number of transactions using the entry + 6. expiration time, can be negative if already expired + show env [] Dump one or all environment variables known by the process. Without any argument, all variables are dumped. With an argument, only the specified