[mapserver-commits] r12534 - in trunk/docs/en: . mapcache
svn at osgeo.org
svn at osgeo.org
Fri Sep 9 14:02:08 EDT 2011
Author: tbonfort
Date: 2011-09-09 11:02:08 -0700 (Fri, 09 Sep 2011)
New Revision: 12534
Added:
trunk/docs/en/mapcache/
trunk/docs/en/mapcache/index.txt
trunk/docs/en/mapcache/mapcache_config.txt
trunk/docs/en/mapcache/mapcache_install.txt
trunk/docs/en/mapcache/mapcache_seed.txt
Modified:
trunk/docs/en/documentation.txt
Log:
add initial stub of mapcache documentation
Modified: trunk/docs/en/documentation.txt
===================================================================
--- trunk/docs/en/documentation.txt 2011-09-09 14:55:28 UTC (rev 12533)
+++ trunk/docs/en/documentation.txt 2011-09-09 18:02:08 UTC (rev 12534)
@@ -28,6 +28,7 @@
installation/index
mapfile/index
mapscript/index
+ mapcache/index
input/index
output/index
ogc/index
Added: trunk/docs/en/mapcache/index.txt
===================================================================
--- trunk/docs/en/mapcache/index.txt (rev 0)
+++ trunk/docs/en/mapcache/index.txt 2011-09-09 18:02:08 UTC (rev 12534)
@@ -0,0 +1,56 @@
+.. _mapcache:
+
+*****************************************************************************
+ Mapserver MapCache
+*****************************************************************************
+
+:Author: Thomas Bonfort
+:Contact: tbonfort at terriscope.fr
+
+MapCache is an apache module that implements a tile caching solution to speed up
+access to WMS layers. The primary objectives are to be fast and easily deployable,
+while offering the essential features (and more!) expected from a tile caching
+solution.
+
+
+.. toctree::
+ :maxdepth: 1
+
+ mapcache_install
+ mapcache_config
+ mapcache_seed
+
+Features
+-----------------------------------------------------------------------------
+
+* services WMS, WMTS, TMS, VirtualEarth/Bing and [ServicingGmaps Gmaps] requests
+* ability to respond to untiled WMS requests by merging tiles from the cache or
+ forwarding them to the wms source
+* responds to WMS/WMTS GetFeatureInfo requests (forwarded to source service)
+* KML superoverlay generation
+* data provided by WMS backends (GDAL supported sources planned)
+* cache types:
+
+ * disk:
+
+ * by default the same cache structure as TileCache and MapProxy
+ * template based, e.g. /path/to/{tileset}/{z}/{x}/{y}.{ext}
+ * sqlite:
+
+ * custom sqlite schema
+ * mbtiles
+ * custom sqlite queries (provide your own)
+ * memcached
+* configurable metatiling
+* on-the-fly tile merging for combining multiple tiles into a single image
+* image post-processing (recompression and quantization) when arriving from a backend
+* interprets and produces cache control headers: Last-Modified, If-Modified-Since, Expires
+* multithreaded seeding utility, that can seed specific zoom levels or specific areas ( e.g.: seed
+ levels 0 to 12 of all tiles intersecting Colorado )
+* ability to add a custom watermark on stored tiles
+* produces a CGI/fastCGI executable for using with other webservers than apache
+* configurable symbolic linking of blank tiles to gain disk storage
+* configurable error reporting: plain http error code, textual message, or empty (blank) image
+* ability to specify vendor params or dimensions to be forwarded to the WMS backend
+ (and build a cache that takes these parameters into account)
+
Added: trunk/docs/en/mapcache/mapcache_config.txt
===================================================================
--- trunk/docs/en/mapcache/mapcache_config.txt (rev 0)
+++ trunk/docs/en/mapcache/mapcache_config.txt 2011-09-09 18:02:08 UTC (rev 12534)
@@ -0,0 +1,506 @@
+.. _mapcache_config:
+
+*****************************************************************************
+ Mapserver MapCache 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>
+
+Concepts
+--------------------------------------------------------------------------------
+
+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&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>
+ </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 on an area, and consists of a
+spatial reference, a geographic extent, resolutions, and tile sizes.
+
+There are for now two predefined grids you can use with "default" openlayers
+settings:
+
+* the "WGS84" grid corresponds to the grid that openlayers will request if
+ you use:
+
+.. code-block:: javascript
+
+ var layer = new OpenLayers.WMS("foobar","http://myserver/mapcache",{LAYERS:layername});
+
+* the "g" grid corresponds to the case when you wish to overlay tiles on top of googlemaps:
+
+.. code-block:: javascript
+
+ var options = {
+ projection: new OpenLayers.Projection("EPSG:900913"),
+ units: "m",
+ maxResolution: 156543.0339,
+ maxExtent: new OpenLayers.Bounds(-20037508.34, -20037508.34, 20037508.34,20037508.34) };
+
+ map = new OpenLayers.Map( 'map', options );
+ var gmap = new OpenLayers.Layer.Google("Google Streets",
+ {
+ 'sphericalMercator': true,
+ 'maxExtent': new OpenLayers.Bounds(-20037508.34,-20037508.34,20037508.34,20037508.34),
+ visibility: true
+ }
+ );
+
+ var wms = new OpenLayers.Layer.WMS(
+ "WMS",
+ "/mapcache",
+ { layers: 'osm', },
+ {
+ gutter:0,
+ ratio:1
+ });
+
+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"/>
+
+
+Miscelaneous
+================================================================================
+
+.. 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>
Added: trunk/docs/en/mapcache/mapcache_install.txt
===================================================================
--- trunk/docs/en/mapcache/mapcache_install.txt (rev 0)
+++ trunk/docs/en/mapcache/mapcache_install.txt 2011-09-09 18:02:08 UTC (rev 12534)
@@ -0,0 +1,10 @@
+.. _mapcache_install:
+
+*****************************************************************************
+ Mapserver MapCache Compilation/Installation Instructions
+*****************************************************************************
+
+:Author: Thomas Bonfort
+:Contact: tbonfort at terriscope.fr
+
+TBD
Added: trunk/docs/en/mapcache/mapcache_seed.txt
===================================================================
--- trunk/docs/en/mapcache/mapcache_seed.txt (rev 0)
+++ trunk/docs/en/mapcache/mapcache_seed.txt 2011-09-09 18:02:08 UTC (rev 12534)
@@ -0,0 +1,121 @@
+.. _mapcache_seed:
+
+*****************************************************************************
+ MapCache Seeder
+*****************************************************************************
+
+:Author: Thomas Bonfort
+:Contact: tbonfort at terriscope.fr
+
+Mod-mapcache ships whith an advanced seeding tool, whose main features are:
+ * configurable number of seeding threads, to speed up the rendering.
+ * ability to reseed tiles older than a certain timestamp
+ * ability to seed tiles given a shapefile/ogr datasource
+
+Usage
+-----------------------------------------------------------------------------
+
+The seeding utility is named mapcache_seed, and is located in the mapcache/src/
+directory of the project
+
+
+Commandline options
+================================================================================
+
+::
+
+ -c [file] : path to the mapcache.xml configuration file that contains the
+ tilesets that need to be seeded.
+ -t [tileset]: name of the tileset that must be seeded
+ -g [grid]: name of the grid that must be seeded (the selected
+ tileset must reference the given grid)
+ -z minzoom,maxzoom: (optional) start and end zoom levels that must be seeded.
+ -e minx,miny,maxx,maxy: (optional) bounding box of the area to seed
+ -o (timestamp|now): (optional) only seed tiles that are older than the given value.
+ The value can either be the string "now", or a date formatted
+ like year/month/day hour:minute, eg: "2011/01/31 20:45".
+ (note that a full timestamp should be quoted).
+ -n nthreads: number of parallel threads that should be used to request
+ tiles from the wms source. The default is 1, but can be set higher
+ if the WMS server can withstand parallel requests (as a rule of thumb,
+ the value chosen here should never be much higher than the number
+ of cpus on the wms server)
+ -q: don't print progress messages to the standard output
+ -D "DIMENSION=VALUE": used to specify which dimension to use if the tileset supports
+ dimensions. Can be used multiple times to set multiple
+ dimensions, e.g. -D "DIM1=VAL1" -D "DIM2=VAL2"
+
+Optional Commandline options when using OGR/GEOS
+================================================================================
+
+At compile time, if ogr and geos where found on the system, the seeder tool
+supports additional options to seed only the tiles that cover an arbitrary
+geographical area. *Important:* Note that for the time being, the OGR
+datasource should be in the same projection as the grid you are seeding, as
+there is no automatic reprojection from the datasource projection to the grid
+projection.
+
+::
+
+ -d [ogr_datasource]: ogr connection to the spatial source. Consult the OGR
+ documentation for all that is supported. In the simplest case (e.g. a
+ Shapefile), this is just the full filename of the shapefile
+ -l [ogr_layer]: (optional) for datasources that contain multiple layers (e.g. postgis, with
+ multiple tables), determines which layer will be used
+ -s [ogr_sql]: OGR sql expression that can be applied (see http://www.gdal.org/ogr/ogr_sql.html )
+ -w [ogr_where]: sql "where" expression to filter out returned values. This would
+ typically be used to select only the geometry of a given country if the
+ datasource contains all the world contours
+
+Important Note
+================================================================================
+
+The seeding utility must be run under the same user account as the
+user running the webserver. This is required so the permissions on the tiles
+created by the seeder are accessible by the webserver, and conversely so the
+seeder has the rights to write files to directories created by the webserver.
+
+
+A sample seeding session goes like this:
+
+::
+
+ [user at host]$ sudo www-data
+ [www-data at host]$ /path/to/mapcache/src/mapcache_seed -c /path/to/www/conf/mapcache.xml [[options]]
+ [www-data at host]$ logout
+ [user at host]$
+
+
+Examples
+================================================================================
+
+Seed the "osm" tileset with the "g" (google/web-mercator) grid:
+::
+
+ ./src/mapcache_seed -c mapcache.xml -t osm -g g
+
+Seed levels 0 through 12:
+::
+
+ ./src/mapcache_seed -c mapcache.xml -t osm -g g -z 0,12
+
+Given a shapefile that contains the world country countours, seed only the
+areas that are covered by land (i.e. skip the oceans). Also use 4 request
+threads in parallel:
+::
+
+ ./src/mapcache_seed -c mapcache.xml -t osm -g g -z 0,12 -n 4 -d /path/to/seed.shp
+
+Same as beforehand, but only seed the USA (notice the quote usage, required to
+create valid sql with a single-quoted 'US':
+::
+
+ ./src/mapcache_seed -c mapcache.xml -t osm -g g -z 0,12 -n 4 -d /path/to/seed.shp -w "FIPS_A2='US'"
+
+Reseed levels 0 to 12 (this could also be done by deleting the cache for levels
+0 to 12 and doing a classic seed, but doing so this way does not slow down the
+access from web clients):
+::
+
+ ./src/mapcache_seed -c mapcache.xml -t osm -g g -z 0,12 -o now
+
More information about the mapserver-commits
mailing list