.. _mapcache_config:

*****************************************************************************
Configuration File
*****************************************************************************

:Author: Thomas Bonfort
:Contact: tbonfort at terriscope.fr

The configuration files determines what and how mod-mapcache will serve
incoming requests. It is an xml file that comprises a list of entries, as
outlined here:

.. code-block:: xml

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

.. _mapcache_sources:

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 no other
sources than WMS implemented, others may be added later if the need
arises)

.. code-block:: xml
   
   <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 that will 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 request. make sure you know what you are 
            doing when adding a header 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.
         -->
         <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 `<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.

.. code-block:: xml
   
   <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">
      <!-- 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} : a string that concatenates the tile's dimension
          - {ext} : the filename extension for the tile's image format
          - {x},{y},{z} : the tile x,y,z values
          - {inv_x}, {inv_y}, {inv_z} : 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 chose creates a unique
           filename for your given tilesets. e.g. do not ommit 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">
      <!-- base
           
           absolute filesystem path where the sqlite database files will be stored.
           this directory needs to be readable and writable by the user running
           apache
      -->
      <dbname_template>/tmp/{tileset}-{grid}.db</dbname_template>
      <!-- hitstats
           log last access time and total number of hits for each tile in the cache.
           note that this slows the tile accesses drastically as it requires a write
           to the database for each tile access
      -->
      <hitstats>false</hitstats>
   </cache>

   <cache name="mbtiles" type="mbtiles">
      <dbname_template>/Users/tbonfort/Documents/MapBox/tiles/natural-earth-1.mbtiles</dbname_template>
   </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.

.. code-block:: xml
   
   <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 is obtained by leving out this tag.
      -->
      <compression>fast</compression>

      <!-- colors

         if supplied, this enables png quantization which reduces the number of colors
         in an image to atain 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 and produces the smallest images. can also be "rgb"
          which ususally 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>



.. _mapcache_grids:

Grid
================================================================================

A grid is the matrix that maps tiles on 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 to positive integers separated by a space character. The most 
  common entry for this is:
  
  .. code-block:: xml
  
     <size>256 256</size>

* **<extent>**: The geographical extent covered by the grid, in ground units (e.g.
  meters, degrees, feet, ...). Must be specified as 4 floating point numbers 
  separated be spaces, order like minx, miny, maxx, maxy. The (minx,miny) point
  defines the origin of the grid, i.e. the pixel at the bottom left of the bottom-
  leftmost 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.
  
  .. code-block:: xml
  
     <extent>-180 -90 180 90</extent>

* **<srs>**: The projection of the grid, usually given by it epsg identifier. The
  actual meaning of the value put here isn't used directly by mapcache to compute
  reprojections, it is only used to lookup which grid to use when receiving WMS
  requests.
  
  .. code-block:: xml
  
     <srs>epsg:4326</srs>

  .. note::
    
    This is the value that is passed on to the :ref:`source <mapcache_sources>`
    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 capabilites
  document. Allowed values are:

  * **m**: meters
  * **dd**: decimal degrees
  * **ft**: feet
  
  .. code-block:: xml
  
     <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 a space 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).
    
  .. code-block:: xml
  
    <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 usefull if
  the epsg id for a given projection has evolved over time, or to support other
  catalogues than the epsg one (which is the only catalog supported by the wms
  specification).
  
  .. code-block:: xml

    <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.

    .. code-block:: xml

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

  * **<WellKnownScaleSet>**: see the WMTS keyword. This will add a
    WellKnownScaleSet entry to the WMTS capabilites document. It is up to the
    user to make sure that the supplied resolutions for the grid actually match
    the pre-defined WellKnownScaleSet.
    
    .. code-block:: xml
      
      <WellKnownScaleSet>urn:ogc:def:wkss:OGC:1.0:GoogleCRS84Quad</WellKnownScaleSet>


Preconfigured Grids
--------------------------------------------------------------------------------

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

* the "WGS84" grid corresponds to a grid where the whole world is rendered on
  2 times 1  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.

  .. code-block:: xml

     <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 corresponds to the case when you wish 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.

  .. code-block:: xml
     
     <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: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
  its default srs is EPSG:3857 instead of EPSG:900913.

  .. code-block:: xml
  
     <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*.  

.. code-block:: xml

   <tileset name="test">

      <!-- source: the "name" attribute of a preconfigured <source> -->
      <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 way 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.

         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">WGS84</grid>
         <grid>g</grid>

      <!-- metadata
         optional metadata tags used for responding to GetCapabilities request.
         you can put anything in here, although only the title and abstract tags
         are currently used to populate the GetCapabilities document.
      -->
      <metadata>
         <title>vmap0 map</title>
         <abstract>blabla</abstract>
      </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 of 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 on tiles already
         stored in the cache, nor on newly stored tiles until the server is restarted
      <watermark>/home/tbonfort/dev/mod-mapcache/static/watermark.png</watermark>
      -->
      
      <!-- format
         (optional) format to use when storing a tile. this should be a format with high
         compression, eg. png with compression "best", as the compression operation is only
         done once at creation time.
         if left out, no recompression is applied to the image, 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 a recompression has to 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 using this, the configured source must be instructed not to put any labels inside
         this area, as otherwise this will result in truncated labels (for mapserver, this is
         the "labelcache_map_edge_buffer" "-10" metadata entry, along with label PARTIALS FALSE
      -->
      <metabuffer>10</metabuffer>

      <!-- expires
         optional expiration value in seconds for a tile. this is expressed in a number of seconds
         after the 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 on the caches. See <auto_expire> for that.
      -->
      <expires>3600</expires>

      <!-- auto_expire
         automatically re-request tiles and update the cache once they are older than the given number
         of seconds after their creation.
         Note that this will only delete tiles form 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>
      -->
      <auto_expire>86400</auto_expire>
      
      <!-- dimensions
         optional dimensions that should be cached
         the order of the <dimension> tags inside the <dimensions> is important as it is used
         to create the directory structure for the disk cache. i.e. if you change the order of these
         values, any tiles that have been previously cached are invalidated (but not removed from the 
         cache, it's just they don't exist anymore 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 base/gridname/DIM1/value/xx/xx/xx/xx/xx/xx.png
               file. i.e. their are as many different caches created as their 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
            spearated by slashes (/) and finishing with ".map" ( [a-zA-Z0-9\./]*\.map$ ) , but will faill 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.
            eg: 
               * 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.

.. code-block:: xml

   <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 treated 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 the tiles from the cache
             - 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>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"/>

   
Miscellaneous
================================================================================

.. code-block:: xml

   <!-- default_format
      format to use when a client asks for an image that is dynamically created from multiple
      tiles from the cache.
      note that using a png format with "best" compression is not recommended
      here as it comes with a very compression overhead in terms of cpu processing. it is
      recommended 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 will be responded to by mod-mapcache
      each service is accessible at the url http://host/path/to/mapcache/{service},
      eg http://myhost/mapcache/wms for OGC WMS.
   -->

   <!-- errors
        configure how error 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>

   
   <!--
        location 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
   -->
   <lock_dir>/tmp</lock_dir>

   <!--
        interval in microseconds to sleep before checking that a lockfile is still present.
        default is 1/100th of a second (i.e. 10000 microseconds)
   -->
   <lock_retry>10000</lock_retry>
   
   <!-- log_level
      For CGI/FastCGI only - For the apache module use the httpd.conf
      LogLevel key.
      Defines the verbosity of the what is sent to the logs.
        - 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>