| Home | Products | Issue Tracker | Service Providers | FAQ | Twitter | Download

# Configuration File

Author

  Thomas Bonfort

Contact

  tbonfort at terriscope.fr

The configuration file determines how mod-mapcache will serve incoming requests. It is an XML file comprising a list of entries, as outlined here:

    <mapcache>
       <grid>....</grid>
       <source>....</source>
       <cache>...</cache>
       <format>...</format>
       <tileset>...</tileset>
       <service>...</service>
    </mapcache>

Note

The MapCache configuration file is only read when the Apache web server starts and the MapCache module is loaded. If you modify this file you will have to restart Apache for the changes to take effect.

## Source

A source is a service mod-mapcache can query to obtain image data. This is typically a WMS server accessible by a URL. (There are currently only WMS, WMTS and mapfile as sources, though others may be added later if the need arises, see Data Sources).

    <source name="vmap0" type="wms">

       <!--
          Extra parameters that will be added to the GetMap request. You can
          specify any parameter here, e.g. VERSION if you want to override the
          version of the WMS request.

          The LAYERS parameter is mandatory.

          Usual parameters here are FORMAT, or MAP if using MapServer.
       -->
       <getmap>
          <params>
             <FORMAT>image/png</FORMAT>
             <LAYERS>basic</LAYERS>
          </params>
       </getmap>

       <!-- HTTP URL and parameters to be used when making WMS requests -->
       <http>

          <!-- URL of the WMS service, without any parameters -->
          <url>http://vmap0.tiles.osgeo.org/wms/vmap0</url>

          <!--
             HTTP headers added to the request. Make sure you know what you are
             doing when adding headers here, as they take precedence over any
             default headers curl will be adding to the request.

             Typical headers that can be added here are User-Agent and Referer.

             When adding a <key>value</key> element here, the request to the WMS
             source will contain the

             key: value\r\n

             HTTP header.

             You may also forward a header from the incoming client request using
             the <MyHeader>{X-Header-To-Forward}<MyHeader> syntax.
          -->
          <headers>
             <User-Agent>mod-mapcache/r175</User-Agent>
             <Referer>http://www.mysite.com?param=2&amp;par=4</Referer>
          </headers>

          <!-- Timeout in seconds before bailing out from a request -->
          <connection_timeout>30</connection_timeout>
       </http>
    </source>

The name and type attributes are straightforward: type is “wms”, and name is the key by which this source will be referenced; <url> is the HTTP location where the service can be accessed; and <wmsparams> is a list of parameters that will be added to the WMS request. You should probably at the very least add the FORMAT and LAYERS parameters. By convention(?), WMS parameters are uppercase, and you should respect this convention in your configuration file.

This is where you can also override some default WMS parameters if needed. By default, the parameters that will be used are: <REQUEST>GetMap</REQUEST> <SERVICE>WMS</SERVICE> <STYLES></STYLES> <VERSION>1.1.0</VERSION>

## Cache

A cache is a location where received tiles will be stored.

    <cache name="disk" type="disk">

       <!-- base

            Absolute filesystem path where the tile structure will be stored.

            This directory needs to be readable and writable by the user running
            Apache.
       -->
       <base>/tmp</base>

       <!-- symlink_blank

            Enable blank (i.e. uniform color) tile detection. Blank tiles will be
            detected at creation time and linked to a single blank tile on disk
            to preserve disk space.
       -->
       <symlink_blank/>
    </cache>

    <cache name="tmpl" type="disk" layout="template">
       <!-- template

            String template that will be used to map a tile (by tileset, grid
            name, dimension, format, x, y, and z) to a filename on the filesystem.

            The following replacements are performed:

            - {tileset}               : the tileset name
            - {grid}                  : the grid name
            - {dim}                   : string concatenating the tile's dimension
            - {ext}                   : tile's image-format filename extension
            - {x},{y},{z}             : tile's x,y,z values
            - {inv_x},{inv_y},{inv_z} : inverted x,y,z values

            (For inverted x,y,z values, (inv_x = level->maxx - x - 1). This is
            mainly used to support grids where one axis is inverted (e.g. the
            Google schema) and you want to create on offline cache.)

          * Note that this type of cache does not support blank-tile detection
            and symlinking.

          * Warning: It is up to you to make sure that the template you choose
            creates a unique filename for your given tilesets (e.g. do not omit
            the {grid} parameter if your tilesets reference multiple grids.)
            Failure to do so will result in filename collisions!

       -->
       <template>/tmp/template-test/{tileset}#{grid}#{dim}/{z}/{x}/{y}.{ext}</template>
    </cache>

    <!-- memcache cache

         Entry accepts multiple <server> entries.

         Requires a fairly recent apr-util library and headers.
    -->
    <cache name="memcache" type="memcache">
       <server>
          <host>localhost</host>
          <port>11211</port>
       </server>
    </cache>

    <!-- sqlite cache

         Requires building with "with-sqlite".
    -->
    <cache name="sqlite" type="sqlite3">
       <!-- dbfile

            Absolute filename path of the SQLite database file to use.

            This file needs to be readable and writable by the user running the
            MapCache instance.
       -->
    </cache>

    <cache name="mbtiles" type="mbtiles">
       <dbfile>/path/to/MapBox/tiles/natural-earth-1.mbtiles</dbfile>
    </cache>

## Format

A format is an image format that will be used to return tile data to clients, and to store tile data on disk.

    <format name="PNGQ_FAST" type ="PNG">

       <!-- compression

            PNG compression: best or fast

            Note that "best" compression is CPU intensive for little gain over
            the default default compression obtained by leaving out this tag.
       -->
       <compression>fast</compression>

       <!-- colors

            If supplied, this enables PNG quantization which reduces the number
            of colors in an image to attain higher compression. This operation is
            destructive, and can cause artifacts in the stored image.

            The number of colors can be between 2 and 256.
      -->
      <colors>256</colors>
    </format>
    <format name="myjpeg" type ="JPEG">

       <!-- quality

            JPEG compression quality, ranging from 0 to 100.

            95 produces high quality images with few visual artifacts. Values
            under around 80 produce small images but with visible artifacts.
            YMMV.
       -->
       <quality>75</quality>

       <!-- photometric

           Photometric interpretation of the bands created in the JPEG image.

           Default is "ycbcr", which produces the smallest images. Can also be
           "rgb", which usually results in x2 or x3 image sizes.
       -->
       <photometric>ycbcr</photometric>

    </format>

    <format name="PNG_BEST" type ="PNG">
       <compression>best</compression>
    </format>

    <format name="mixed" type="MIXED">
       <transparent>PNG_BEST</transparent>
       <opaque>JPEG</opaque>
    </format>

## Grid

A grid is the matrix that maps tiles onto an area, and consists of a spatial reference, a geographic extent, resolutions, and tile sizes.

### Mandatory Configuration Options

- <size>: The width and height of an individual tile, in pixels. Must be specified as positive integers separated by a space character. The most common tile size is:

      <size>256 256</size>

- <extent>: The geographical extent covered by the grid, in ground units (e.g. meters, degrees, feet, etc.). Must be specified as 4 floating point numbers separated by spaces, ordered as minx, miny, maxx, maxy.

  MapCache expects all of its extents to be given in lonlat, and does the translation to latlon at request time if needed.

  The (minx,miny) point defines the origin of the grid, i.e. the pixel at the bottom left of the bottom-left most tile is always placed on the (minx,miny) geographical point.

  The (maxx,maxy) point is used to determine how many tiles there are for each zoom level.

      <extent>-180 -90 180 90</extent>

- <srs>: The projection of the grid, usually given by it EPSG identifier. This value isn’t used directly by MapCache to compute reprojections; it is only used to look up which grid to use when receiving WMS requests.

      <srs>epsg:4326</srs>

  Note

  This is the value that is passed on to the source when requesting a tile that is not already cached for the current grid. You must make sure that the source that is queried is capable of returning image data for this SRS.

- <units>: The ground units used by the grid’s projection. This entry is not used directly by MapCache aside from calculating scales for the WMTS capabilities document. Allowed values are:

  - m : meters

  - dd : decimal degrees

  - ft : feet

      <units>dd</units>

- <resolutions>: This is a list of resolutions for each of the zoom levels defined by the grid. This must be supplied as a list of positive floating point values, separated by spaces and ordered from largest to smallest. The largest value will correspond to the grid’s zoom level 0. Resolutions are expressed in “units-per-pixel”, depending on the unit used by the grid (e.g. resolutions are in meters per pixel for most grids used in webmapping).

      <resolutions>0.703125000000000 0.351562500000000 0.175781250000000 8.78906250000000e-2 4.39453125000000e-2 2.19726562500000e-2 1.09863281250000e-2 5.49316406250000e-3 2.74658203125000e-3 1.37329101562500e-3 6.86645507812500e-4 3.43322753906250e-4 1.71661376953125e-4 8.58306884765625e-5 4.29153442382812e-5 2.14576721191406e-5 1.07288360595703e-5 5.36441802978516e-6</resolutions>

### Optional Configuration Options

- <srsalias>: This tag can be specified multiple times, and allows the user to add multiple SRS entries for a given grid. This is especially useful if the EPSG id for a given projection has evolved over time, or to support catalogs other than the EPSG one (which is the only catalog supported by the WMS specification).

      <srs>EPSG:310024802</srs>
      <srsalias>IGNF:GEOPORTALFXX</srsalias>
      <srsalias>EPSG:310024001</srsalias>

- <metadata>:

  - <title>: The name of the grid, in human readable form. Appears in the capabilities documents.

        <title>This grid covers the area blah blah blah</title>

  - <WellKnownScaleSet>: See the WMTS keyword. This will add a WellKnownScaleSet entry to the WMTS capabilities document. It is up to the user to make sure that the supplied resolutions for the grid actually match the pre-defined WellKnownScaleSet.

        <WellKnownScaleSet>urn:ogc:def:wkss:OGC:1.0:GoogleCRS84Quad</WellKnownScaleSet>

- <origin>: Specifies the origin of the grid. Valid values are top-left, bottom-left, top-right and bottom-right.

  If not used, the grid will have the bottom-left corner as reference point.

      <origin>top-left</origin>

### Preconfigured Grids

There are three predefined grids you can use without defining them in the mapcache.xml file:

- The “WGS84” grid corresponds to a grid where the whole world is rendered on two 256x256-pixel tiles at level 0 (i.e. the (-180,-90,180,90) extent fits on a 512x256 image). It goes down to zoom level 17.

      <grid name="WGS84">
         <metadata>
            <title>GoogleCRS84Quad</title>
            <WellKnownScaleSet>urn:ogc:def:wkss:OGC:1.0:GoogleCRS84Quad</WellKnownScaleSet>
         </metadata>
         <extent>-180 -90 180 90</extent>
         <srs>EPSG:4326</srs>
         <units>dd</units>
         <size>256 256</size>
         <resolutions>0.703125000000000 0.351562500000000 0.175781250000000 8.78906250000000e-2 4.39453125000000e-2 2.19726562500000e-2 1.09863281250000e-2 5.49316406250000e-3 2.74658203125000e-3 1.37329101562500e-3 6.86645507812500e-4 3.43322753906250e-4 1.71661376953125e-4 8.58306884765625e-5 4.29153442382812e-5 2.14576721191406e-5 1.07288360595703e-5 5.36441802978516e-6</resolutions>
      </grid>

- The “g” grid may be used to overlay tiles on top of GoogleMaps, and is the default tiling scheme used in webmapping applications. This grid goes down to zoom level 18. Level 0 is a single 256x256 tile. This grid’s default SRS is EPSG:900913, which is non-standard but in wider use than than its official EPSG:3857 entry.

      <grid name="g">
         <metadata>
            <title>GoogleMapsCompatible</title>
            <WellKnownScaleSet>urn:ogc:def:wkss:OGC:1.0:GoogleMapsCompatible</WellKnownScaleSet>
         </metadata>
         <extent>-20037508.3427892480 -20037508.3427892480 20037508.3427892480 20037508.3427892480</extent>
         <srs>EPSG:900913</srs>
         <srsalias>EPSG:3857</srsalias>
         <units>m</units>
         <size>256 256</size>
         <resolutions>156543.0339280410 78271.51696402048 39135.75848201023 19567.87924100512 9783.939620502561 4891.969810251280 2445.984905125640 1222.992452562820 611.4962262814100 305.7481131407048 152.8740565703525 76.43702828517624 38.21851414258813 19.10925707129406 9.554628535647032 4.777314267823516 2.388657133911758 1.194328566955879 0.5971642834779395</resolutions>
      </grid>

- The “GoogleMapsCompatible” grid is nearly identical to the “g” grid, except that its default SRS is EPSG:3857 instead of EPSG:900913.

      <grid name="GoogleMapsCompatible">
         <metadata>
            <title>GoogleMapsCompatible</title>
            <WellKnownScaleSet>urn:ogc:def:wkss:OGC:1.0:GoogleMapsCompatible</WellKnownScaleSet>
         </metadata>
         <extent>-20037508.3427892480 -20037508.3427892480 20037508.3427892480 20037508.3427892480</extent>
         <srs>EPSG:3857</srs>
         <srsalias>EPSG:900913</srsalias>
         <units>m</units>
         <size>256 256</size>
         <resolutions>156543.0339280410 78271.51696402048 39135.75848201023 19567.87924100512 9783.939620502561 4891.969810251280 2445.984905125640 1222.992452562820 611.4962262814100 305.7481131407048 152.8740565703525 76.43702828517624 38.21851414258813 19.10925707129406 9.554628535647032 4.777314267823516 2.388657133911758 1.194328566955879 0.5971642834779395</resolutions>
      </grid>

## Tileset

A tileset is the essential configuration item for mod-mapcache, and corresponds to a set of tiles coming from a source, stored in a cache, and returned to the client in a given format.

    <tileset name="test">

       <!-- source

            The "name" attribute of a preconfigured <source>.

            If the tileset does not contain a <source> element, then it is
            considered read-only and its cache will never be updated. In this
            case, your seeder and webserver would have slightly different
            mapcache.xml files.

            Blank tiles may be dealt with by setting the <errors> directive to
            "empty_img".
       -->
       <source>vmap0</source>

       <!-- cache

            The "name" attribute of a preconfigured <cache>
       -->
       <cache>sqlite</cache>

       <!-- grid

            The "name" attribute of a preconfigured <grid>.

            You can also use the following notation to limit the area that will
            be cached and served to clients:

            <grid restricted_extent="-10 40 10 50">WGS84</grid>

            This is better than using a grid with a limited extent, as in this
            way the tiles that are already cached are not invalidated should you
            want to modify the restricted extent in the future. When using the
            restricted_extent attribute, you should give the corresponding
            information to the client that will be using the service.

            You can also limit the zoom levels that are cached/accessible by
            using the minzoom and maxzoom attributes.

            A grid may reference a ruleset to impose certain behaviour:

            <grid ruleset="rules">4326</grid>

            NOTE: When adding a <grid> element, you *MUST* make sure that the
            source you have selected is able to return images in the grid's SRS.
       -->
       <grid restricted_extent="-10 40 10 50" minzoom="4" maxzoom="17">WGS84</grid>
       <grid ruleset="rules">4326</grid>
       <grid>g</grid>

       <!-- You may store hidden intermediate levels of tiles to enable higher
            quality output when reassembling tiles. This may be needed when
            caching maps containing labels to avoid the text from becoming too
            small or too blurry when requesting resolutions that are far away
            from the native grid resolutions.

            Supposing grid "mygrid" consists of 256x256 pixel tiles, with
            resolutions r1,r2,r3,r4,...rn, MapCache will populate a hidden grid
            called "mygrid_intermediate_0.5" containing tiles of size
            256+256*0.5=384 with resolutions r1+(r2-r1)*0.5, r2+(r3-r2)*0.5, ...
            r(n-1)+(r(n)-r(n-1)*0.5. That is, a tile with a given extent will be
            stored once in a 256x256 tile, and once in a 384x384 one.

            This intermediate grid is private to MapCache and will not be exposed
            to tiled requests. It will only be used for WMS requests that require
            horizontal assembling.
       -->
       <grid use_wms_intermediate_resolutions="true">mygrid</grid>

       <!-- metadata

            Optional metadata tags used for responding to GetCapabilities
            requests. You can put anything here, but only the title, abstract and
            keywords tags are currently used to populate the GetCapabilities
            document.
       -->
       <metadata>
          <title>vmap0 map</title>
          <abstract>blabla</abstract>
          <keywords>
             <keyword>foo</keyword>
             <keyword>bar</keyword>
          </keywords>
       </metadata>

       <!-- watermark

            Optional tag to add a watermark to the tiles *before* storing them to
            cache. The supplied image MUST be exactly the same size as the size
            as the tiles configured in the <grid>.

            The supplied image is read when the configuration is loaded. If you
            make changes to the image, they will NOT be reflected in tiles
            already stored in the cache, nor on newly stored tiles, until the
            server is restarted.
       -->
       <watermark>/path/to/static/watermark.png</watermark>

       <!-- format

           (Optional) format to use when storing a tile. This should be a format
           with high compression, e.g. PNG with compression "best", as the
           compression operation is only done once at tile creation time. If
           omitted, no recompression is applied to the image and mod-mapcache
           will store the exact image received from the <source>.

           Note that the <format> tag is mandatory if <metatile>, <metabuffer> or
           <watermark> are supplied, as in those cases recompression must be
           done.
       -->
       <format>PNG</format>

       <!-- metatile

            Number of columns and rows to use for metatiling. See
            http://geowebcache.org/docs/current/concepts/metatiles.html
       -->
       <metatile>5 5</metatile>

       <!-- metabuffer

            Area around the tile or metatile that will be cut off to prevent some
            edge artifacts. If this is specified, the configured source must be
            instructed not to put any labels inside this area, as otherwise
            labels will be truncated. (For MapServer, use the
            "labelcache_map_edge_buffer" "-10" metadata entry, along with label
            PARTIALS FALSE.)
       -->
       <metabuffer>10</metabuffer>

       <!-- expires

            Optional tile expiration value in seconds. This is expressed as
            number of seconds after creation date of the tile. This is the value
            that will be set in the HTTP Expires and Cache-Control headers, and
            has no effect on the actual expiration of tiles in the caches (see
            <auto_expire> for that). Defaults to 300 if unset.
       -->
       <expires>3600</expires>

       <!-- auto_expire

            Tiles older (in seconds) than this value will be re-requested and
            updated in the cache. Note that this will only delete tiles from the
            cache when they are accessed: You cannot use this configuration to
            limit the size of the created cache. Note that, if set, this value
            overrides the value given by <expires>. By default tiles don't expire.
       -->
       <auto_expire>86400</auto_expire>

       <!-- dimensions

            Optional dimensions that should be cached.

            The order of the <dimension> tags inside the <dimensions> block is
            important, as it is used to create the directory structure for the
            disk cache. That is, if you change the order of these values, any
            tiles that have been previously cached are invalidated: They are not
            removed from the cache, but they no longer exist for mod-mapcache.
       -->
       <dimensions>
          <!-- values dimension

               The example here creates a DIM1 dimension.

               * WMS and WMTS clients can now add a &DIM1=value to their request
                 string. If they don't specify this key/value, the default will
                 be to use DIM1=foobar.
               * The allowed values for DIM1= are foobar (it is important to add
                 the default value to the allowed values entry), foobarbaz, foo
                 and bar.
               * The value specified for DIM1 will be forwarded to the WMS
                 source.
               * The produced tile will be stored in the file
                 base/gridname/DIM1/value/xx/xx/xx/xx/xx/xx.png. That is, there
                 are as many different caches created as there are values in the
                 <values> tag.
          -->
          <dimension type="values" name="DIM1" default="foobar">foobar,foobarbaz,foo,bar</dimension>

          <!-- regex dimension

               The following creates a MAPFILE dimension, for using the same
               mod-mapcache tileset with different MapServer mapfiles. The name
               of the mapfiles need not be known to mod-mapcache, and can
               therefore be created even after mod-mapcache has been started.

               When a user passes a MAPFILE=/path/to/mapfile, the string
               "/path/to/mapfile" is validated against the supplied (PCRE)
               regular expression. The one in this example allows a name composed
               of aphanumeric characters separated by slashes (/) and ending in
               ".map" ( [a-zA-Z0-9\./]*\.map$ ), but will fail if there are two
               consecutive dots (..) in the path, to prevent filesystem traversal
               ( (?!.*\.\.) ).
          -->
          <dimension type="regex" name="MAPFILE" default="/path/to/mapfile.map">^(?!.*\.\.)[a-zA-Z0-9\./]*\.map$</dimension>

          <!-- intervals dimension

               The syntax is the same as common-ows, i.e. a comma-separated list
               of "min/max/resolution" entries, e.g:

               * 0/5000/1000 allows the values 0,1000,2000,3000,4000 and 5000.
               * 0/100/0 allows any values between 0 and 100.
               * Both values can be combined: 0/5000/1000,0/100/0.
          -->
          <dimension name="ELEVATION" type="intervals" default="0">0/5000/1000</dimension>

          <!-- Coming in a future version: support for ISO8601 date/time dimensions -->

       </dimensions>
    </tileset>

## Services

Services are the type of request that mod-mapcache will respond to. You should, of course, enable at least one.

    <service type="wms" enabled="true">
       <!--
            This service should actually be called "ogc". It is different from
            the other services as it does not listen on the /wms endpoint, but
            directly on /. It will intercept WMS GetMap requests that can be
            satisfied from configured tilesets, and can optionally forward all
            the rest to (an)other server(s).

            TODO: This needs way more documenting.

       <forwarding_rule name="foo rule">
         <append_pathinfo>true</append_pathinfo>
         <http>
           <url>http://localhost/mapcacheproxy</url>
         </http>
       </forwarding_rule>
       -->

       <!-- full_wms

            Configure response to WMS requests that are not aligned to a
            tileset's grids. Responding to requests that are not in the SRS of a
            configured grid is not supported, but this should never happen as
            only the supported SRSs are publicized in the capabilities document.

            Allowed values are:

            - error    : Return a 404 error (default).
            - assemble : Build the full image by assembling cached tiles.
            - forward  : Forward the request to the configured source.
       -->
       <full_wms>assemble</full_wms>

       <!-- resample mode

            Filter applied when resampling tiles for full WMS requests. Can be
            either:

            - nearest  : Fastest, poor quality.
            - bilinear : Slower, higher qulity.
       -->
       <resample_mode>bilinear</resample_mode>

       <!-- format

            Image format to use when assembling tiles.
       -->
       <format allow_client_override="true">myjpeg</format>

    </service>
    <service type="wmts" enabled="true"/>
    <service type="tms" enabled="true"/>
    <service type="kml" enabled="true"/>
    <service type="gmaps" enabled="true"/>
    <service type="ve" enabled="true"/>
    <service type="demo" enabled="true"/>

## Ruleset

A ruleset contains a set of rules to impose certain behaviour on zoom levels. It is referenced from a grid element inside a tileset. See tileset for more information.

It is possible to define rules that:

- Puts limits on the visible extent of zoom levels.

    <ruleset name="rules">

       <!-- rule

            A rule impose certain behaviour on one or more zoom levels.
            There is no limit on the number of rules.

            zoom_level attribute contains the levels affected by this rule.
            A zoom level can not be referenced by multiple rules.
       -->
       <rule zoom_level="4 5 6 7">

          <!-- visibility

               Contains a collection of visible extents.

               Tiles inside these extents will be fetched from the cache.
               Tiles outside will be created on the fly using configured
               color and returned to the client in declared format,
               but not stored in the cache.
               This does not affect the extent announced to the client,
               but will limit the potentially large number of blank tiles
               stored in the cache when data only covers small subsets of
               the total extent.

               hidden_color attribute is the (hex) color (ARGB or RGB) of tiles
               outside the visible extents. Default is a fully transparent tile.
          -->
          <visibility hidden_color="ff000000">

             <!-- extent

                  One or more extents.

                  Extent must be given in the srs of the referencing grid.
             -->
             <extent>228355 6085026 953704 7686970</extent>
          </visibility>
       </rule>

       <rule zoom_level="8 9 10">
          <visibility>
             <extent>335972 6099021 495792 6166722</extent>
             <extent>309336 6166722 644513 6273268</extent>
          </visibility>
       </rule>
    </ruleset>

## Miscellaneous

    <!-- default_format

         Format to use when a client asks for an image that is dynamically
         created from multiple cached tiles. Note that using a PNG format with
         "best" compression is not recommended here as it is computationally
         expensive. It is better to use a PNG format with "fast"compression here,
         unless you have plenty of server CPU power and/or limited bandwidth.
    -->
    <default_format>JPEG</default_format>

    <!-- services

         Services that mod-mapcache will respond to. Each service is accessible
         at the URL http://host/path/to/mapcache/{service}, e.g.
         http://myhost/mapcache/wms for OGC WMS.
    -->

    <!-- errors

         Configure how errors will be reported back to a client:

         - log        : No error is reported back, except an HTTP error code.
         - report     : Return the error message to the client in textual format.
         - empty_img  : Return an empty image to the client. The actual error
                        code is in the X-Mapcache-Error HTTP header.
         - report_img : Return an image with the error text included inside. (Not
                        implemented yet.)

         The default setting is to report the error message back to the user. In
         production, you might want to set this to "log" if you're paranoid, or
         to "empty_img" if you want to play nice with non-conforming clients.
    -->
    <errors>report</errors>

    <locker type="disk">  <!-- this is the default -->
    <!--
         Where to put lockfiles (to block other clients while a metatile is being
         rendered). Defaults to /tmp. This location should be writable by the
         Apache user.
    -->
      <directory>/tmp</directory>
      <retry>0.01</retry> <!-- check back every .01 seconds -->
      <timeout>60</timeout> <!-- Consider a lock stale after this many seconds.
                                 May cause issues if WMS rendering time exceeds
                                 this value. -->
    </locker>

For specific information about locking, read this.

    <!-- log_level

         For CGI/FastCGI only; For the Apache module use the httpd.conf LogLevel
         key.

         Defines the verbosity of logged information. Valid values are:

         - debug
         - info
         - notice
         - warn (default)
         - error
         - crit
         - alert
         - emerg
    -->
    <log_level>warn</log_level>

    <!-- auto_reload

         For FastCGI only. If set to true, the configuration will be
         automatically reloaded if the configuration file has changed. Default is
         false.
    -->
    <auto_reload>true</auto_reload>