|
|
Home | Docs | Issue Tracker | FAQ | Download |
|
|
| 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:
<mapcache>
<grid>....</grid>
<source>....</source>
<cache>...</cache>
<format>...</format>
<tileset>...</tileset>
<services>...</services>
</mapcache>
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)
<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&par=4</Referer>
</headers>
<!-- timeout in seconds before bailing out from a request -->
<connection_timeout>30</connection_timeout>
</http>
</source>
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">
<!-- 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">
<!-- dbfile
absolute filename path of the sqlite database file to use.
this file needs to be readable and writable by the user running
tha mapcache instance
-->
</cache>
<cache name="mbtiles" type="mbtiles">
<dbfile>/path/to/MapBox/tiles/natural-earth-1.mbtiles</dbfile>
</cache>
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 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>
A grid is the matrix that maps tiles on an area, and consists of a spatial reference, a geographic extent, resolutions, and tile sizes.
<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:
<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.
<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.
<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 capabilites document. Allowed values are:
<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).
<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>
<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).
<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 capabilites 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>
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.
<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.
<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.
<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>
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> -->
<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>/path/to/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 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 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"/>
<!-- 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>