Abstract
This document describes the procedures for setting up an OGC compliant Web Map Server (WMS) through the use of MapServer v3.5 (and later).
Last Updated: 2004-05-04
Table of Contents
A WMS (or Web Map Server) allows for use of data from several different servers, and enables for the creation of a network of Map Servers from which clients can build customized maps. The following documentation is based on the Open GIS Consortium's (OGC) Web Map Server Interfaces Implementation Specification v1.1.1.
MapServer v3.5 or more recent is required to implement WMS features. At the time this document was written, Mapserver supports the following WMS versions: 1.0.0, 1.0.7, 1.1.0 (a.k.a. 1.0.8), and 1.1.1.
This document assumes that you are already familiar with certain aspects of MapServer:
MapServer application development and setting up .map files.
Familiarity with the WMS spec would be an asset. A link to the WMS specification document is included in the "WMS-Related Information" section below.
WMS servers interact with their clients via the HTTP protocol. In most cases, a WMS server is a CGI program. This is also the case with MapServer.
The WMS specification defines a number of request types, and for each of them a set of query parameters and associated behaviors. A WMS-compliant server MUST be able to handle at least the following 2 types of WMS requests:
GetCapabilities: return an XML document with metadata of the Web Map Server's information
GetMap: return an image of a map according to the user's needs.
And support for the following types is optional:
GetFeatureInfo: return info about feature(s) at a query (mouse click) location. MapServer supports 3 types of responses to this request:
Text/plain output with attribute info.
Text/html output using MapServer query templates specified in the CLASS template parameter. The MIME type returned by the Class templates defaults to text/html and can be controlled using the metadata "wms_feature_info_mime_type".
Gml features.
DescribeLayer: return an XML description of one or more map layers. This applies only to SLD WMS servers and is not currently supported by MapServer.
With respect to MapServer specifically, it is the "mapserv" CGI program that knows how to handle WMS requests. So setting up a WMS server with MapServer involves installing the mapserv CGI program and a setting up a mapfile with appropriate metadata in it. This is covered in the rest of this document.
The Mapserver WMS Client HOWTO: http://mapserver.gis.umn.edu/doc/wms-client-howto.html
Open GIS Consortium (OGC) Home Page: http://www.opengis.org/
WMS 1.0.0 specification: http://www.opengis.org/docs/00-028.pdf
WMS 1.1.0 specification: http://www.opengis.org/docs/01-047r2.pdf
WMS 1.1.1 specification: http://www.opengis.org/docs/01-068r2.pdf
WMS-Dev mailing list and archive: http://www.intl-interfaces.net/mailman/listinfo/wms-dev
WMS FAQ: http://www.intl-interfaces.net/cookbook/WMS/faq/faqw.py?req=home
WMS XML Capabilities validator: http://www.digitalearth.gov/wmt/xml/validator.html
WMS Cookbook: http://www.intl-interfaces.net/cookbook/WMS/
WMS requests are handled by the "mapserv" CGI program. Not all versions of the mapserv program do include WMS support (it is included by default when you compile together with the PROJ library), so the first step is to check that your mapserv executable includes WMS support. One way to verify this is to use the "-v" command-line switch and look for "SUPPORTS=WMS_SERVER".
Example 1. On Unix:
$ ./mapserv -v
MapServer version 4.2-beta1 OUTPUT=GIF OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP
OUTPUT=PDF OUTPUT=SWF SUPPORTS=PROJ SUPPORTS=FREETYPE SUPPORTS=WMS_SERVER
SUPPORTS=WMS_CLIENT SUPPORTS=WFS_SERVER SUPPORTS=WFS_CLIENT INPUT=POSTGIS
INPUT=OGR INPUT=GDAL INPUT=SHAPEFILE
Example 2. On Windows:
C:\apache\cgi-bin> mapserv -v
MapServer version 4.2-beta1 OUTPUT=GIF OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP
OUTPUT=PDF OUTPUT=SWF SUPPORTS=PROJ SUPPORTS=FREETYPE SUPPORTS=WMS_SERVER
SUPPORTS=WMS_CLIENT SUPPORTS=WFS_SERVER SUPPORTS=WFS_CLIENT INPUT=POSTGIS
INPUT=OGR INPUT=GDAL INPUT=SHAPEFILE
Each instance of WMS server that you setup needs to have its own mapfile. It is just a regular MapServer mapfile in which some parameters and some metadata entries are mandatory. Most of the metadata is required in order to produce a valid GetCapabilites output.
Here is the list of parameters and metadata items that usually optional with MapServer, but are required (or strongly recommended) for a WMS configuration:
At the map level:
Map NAME
Map PROJECTION
Map Metadata (in the WEB Object):
wms_title
wms_onlineresource
wms_srs (unless PROJECTION object is defined using "init=epsg:...")
And for each layer:
Layer NAME
Layer PROJECTION
Layer Metadata
wms_title
wms_srs (optional since the layers inherit the map's SRS value)
Let's go through each of these paramters in more detail:
Map Name and wms_title:
WMS Capabilities requires a Name and a Title tag for every layer. The Map's NAME and wms_title metadata will be used to set the root layer's name and title in the GetCapabilities XML output. The root layer in the WMS context corresponds to the whole mapfile.
Layer Name and wms_title metadata:
Every individual layer needs its own unique name and title. Layer names are also used in GetMap and GetFeatureInfo requests to refer to layers that should be included in the map output and in the query.
Map PROJECTION and wms_srs metadata:
WMS servers have to advertise the projection in which they are able to serve data using EPSG projection codes (see http://www.inovagis.org/giserver/tutorial/epsg.htm for a list of EPSG codes). Recent versions of the PROJ4 library come with a table of EPSG initialization codes and allow users to define a projection like this:
PROJECTION
"init=epsg:4269"
END
(Note that "epsg" has to be in lowercase when used in the PROJ4 'init' directive.)
If the MAP PROJECTION block is provided in the format "init=epsg:xxxx" then MapServer will also use this information to generate a <BoundingBox> tag for the top-level layer in the WMS capabilities document. Note that the BoundingBox is an optional element of WMS capabilities, but it is good practice to allow MapServer to include it when possible.
The above is sufficient for MapServer to recognize the EPSG code and include it in SRS tags in the capabilities output (wms_srs metadata is not required in this case). However, it is often impossible to find an EPSG code to match the projection of your data. In those cases, the "wms_srs" metadata is used to list one or more EPSG codes that the data can be served in, and the PROJECTION object contains the real PROJ4 definition of the data's projection.
Here is an example of a server whose data is in an Lambert Conformal Conic projection (for which there is no EPSG code). It's capabilities output will advertize EPSG:4269 and EPSG:4326 projections (lat/lon), but the PROJECTION object is set to the real projection that the data is in:
NAME DEMO
...
WEB
...
METADATA
"wms_title" "WMS Demo Server"
"wms_onlineresource" "http://my.host.com/cgi-bin/mapserv?map=wms.map&"
"wms_srs" "EPSG:4269 EPSG:4326"
END
END
PROJECTION
"proj=lcc"
"ellps=GRS80"
"lat_0=49"
"lon_0=-95"
"lat_1=49"
"lat_2=77"
END
...
In addition to EPSG:xxxx projections, a WMS server can advertize projections in the AUTO:xxxx namespace. AUTO projections 42001 to 42005 are internally supported by MapServer. However, AUTO projections are useful only with smart WMS clients, since the client needs to define the projection parameters in the WMS requests to the server. For more information see Annex E of the WMS 1.1.1 specification and section 6.5.5.2 of the same document. See also the FAQ on AUTO projections at the end of this document.
Layer PROJECTION and wms_srs metadata:
By default in the WMS context, layers inherit the SRS or their parent layer (the map's projection in the MapServer case). For this reason it is not necessary (but still strongly recommended) to provide PROJECTION and wms_srs for every layer.
However, if your server wants to advertise multiple projections, then at least a PROJECTION object is required in every layer, otherwise the layers won't be reprojected. This is just the way on-the-fly reprojection works in MapServer.
Layer PROJECTION and wms_srs metadata are defined exactly the same way as the map's PROJECTION and wms_srs metadata.
For vector layers, if a PROJECTION block is provided in the format "init=epsg:xxxx" then MapServer will also use this information to generate a <BoundingBox> tag for this layer in the WMS capabilities document. Note that the BoundingBox is an optional element of WMS capabilities, but it is good practice to allow MapServer to include it when possible.
The "wms_onlineresource" metadata:
The wms_onlineresource metadata is set in the map's web object metadata and specifies the URL that should be used to access your server. This is required for the GetCapabilities output. If wms_onlineresource is not provided then MapServer will try to provide a default one using the script name and hostname, but you shouldn't count on that too much. It is strongly recommended that you provide the wms_onlineresource metadata.
See section 6.2.2 of the WMS 1.1.1 specification for the whole story about the online resource URL. Basically, what you need is a complete HTTP URL including the http:// prefix, hostname, script name, potentially a "map=" parameter, and and terminated by "?" or "&".
Here is a valid online resource URL:
http://my.host.com/cgi-bin/mapserv?map=mywms.map&
By creating a wrapper script on the server it is possible to hide the "map=" parameter from the URL and then your server's online resource URL could be something like:
http://my.host.com/cgi-bin/mywms?
This is covered in more detail in the section "More About the Online Resource URL" below.
OK, now that we've got a mapfile, we have to check the XML capabilities returned by our server to make sure nothing is missing.
Using a web browser, access your server's online resource URL to which you add the parameter "REQUEST=GetCapabilities" to the end, e.g.
http://my.host.com/cgi-bin/mapserv?map=mywms.map&REQUEST=GetCapabilities
This should return a document of MIME type application/vnd.ogc.wms_xml, so your browser is likely going to prompt you to save the file. Save it and open it in a text editor (Emacs, Notepad, etc.)
If you get an error message in the XML output then take necessary actions. Common problems and solutions are listed in the FAQ at the end of this document.
If everything went well, you should have a complete XML capabilities document. Search it for the word "WARNING"... MapServer inserts XML comments starting with "<!--WARNING: " in the XML output if it detects missing mapfile parameters or metadata items. If you notice any warning in your XML output then you have to fix all of them before you can register your server with a WMS client, otherwise things are likely not going to work.
OK, now that we know that our server can produce a valid XML GetCapabilities response we should test the GetMap request. MapServer only checks for a few of the required GetMap parameters, so both of the minimum MapServer parameters and a valid GetMap request will be explained below.
Simply adding "VERSION=1.1.1&REQUEST=GetMap&LAYERS=yourlayername1,yourlayername2" to your server's URL should generate a map with the default map size and all the layers with STATUS ON or DEFAULT displayed, e.g.
http://my.host.com/cgi-bin/mapserv?map=mywms.map&VERSION=1.1.1&REQUEST=GetMap&LAYERS=parks,province
(Note that this works with MapServer's WMS interface even though it is an incomplete GetMap request according to the WMS spec. It lacks several mandatory parameters such as SRS, BBOX, etc. The next section explains how to create a valid GetMap request.)
The following is a list of the required GetMap parameters according to the WMS spec:
VERSION=version : Request version
REQUEST=GetMap : Request name
LAYERS=layer_list : Comma-separated list of one or more map layers. Optional if SLD parameter is present.
STYLES=style_list : Comma-separated list of one rendering style per requested layer. Optional if SLD parameter is present. NOTE that MapServer does not support named styles, so most times you would specify "STYLES=" with an empty value. MapServer does support STYLES when used with an SLD.
SRS=namespace:identifier : Spatial Reference System.
BBOX=minx,miny,maxx,maxy : Bounding box corners (lower left, upper right) in SRS units.
WIDTH=output_width : Width in pixels of map picture.
HEIGHT=output_height : Height in pixels of map picture.
FORMAT=output_format : Output format of map.
An valid example would therefore be:
http://my.host.com/cgi-bin/mapserv?map=mywms.map&VERSION=1.1.1&REQUEST=GetMap&LAYERS=prov_bound&STYLES=&SRS=EPSG:4326&BBOX=
-173.537,35.8775,-11.9603,83.8009&WIDTH=400&HEIGHT=300&FORMAT=image/png
If you have access to a WMS client, then register your new server's online resource with it and you should be off and running.
If you don't have your own WMS client installed already, here are a few pointers:
MapServer itself can be used as a WMS client, see the WMS Client HOWTO.
MapLab's MapBrowser is a web-based WMS client.
JUMP is a desktop GIS package which includes WMS client support.
Deegree provides a WMS client.
The owsview Viewer Client Generator is an online application that allows users to add WMS and WFS layers by validating WMS and WFS Capabilities XML.
This list is not exhaustive, there are several Open Source or proprietary packages that offer WMS support and could be used to interact with your new MapServer WMS server instance.
As mentioned in the section "Setup a Mapfile / wms_onlineresource metadata" above, the following Online Resource URL is perfectly valid for a MapServer WMS according to section 6.2.2 or the WMS 1.1.1 specification:
http://my.host.com/cgi-bin/mapserv?map=mywms.map&
However, some people will argue that the above URL contains mandatory vendor-specific parameters and that this is illegal. First we would like to point that "map=..." is not considered a vendor-specific parameter in this case since it is part of the Online Resource URL which is defined as an opaque string terminated by "?" or "&" (See WMS 1.1.1 section 6.2.2).
But anyway, even if it's valid, the above URL is still ugly. And you might want to use a nicer URL for your WMS Online Resource URL. Here are some suggestions:
On Unix servers, you can setup a wrapper shell script that sets the MS_MAPFILE environment variable and then passes control to the mapserv executable... that results on a cleaner OnlineResource URL:
#! /bin/sh
MS_MAPFILE=/path/to/demo.map
export MS_MAPFILE
/path/to/mapserv
Another option is to use the "setenvif" feature of Apache: use symbolic links that all point to a same mapserv binary, and then for each symbolic link test the url, and set the MAP environment accordingly.
For Windows and Apache users the steps are as follows (this requires Apache 1.3 or newer):
Copy mapserv.exe to a new name for your WMS, such as "mywms.exe".
In httpd.conf, add:
SetEnvIf Request_URI "/cgi-bin/mywms" MS_MAPFILE=/path/to/mymap.map
On IIS servers (Windows), you can use the following ASP script:
<%
Server.ScriptTimeout = 360
strRequest = Request.ServerVariables("QUERY_STRING")
strURL = "http://myserver/cgi-bin/mapserv.exe?map=C:\Inetpub\wwwroot\WMS\mymap.map&" & strRequest
Dim objHTTP
Set objHTTP = Server.CreateObject("MSXML2.ServerXMLHTTP")
objHTTP.open "GET", strURL, false
objHTTP.send ""
Response.ContentType = objHTTP.getResponseHeader("content-type")
Response.BinaryWrite objHTTP.responseBody
Set objHTTP = Nothing
%>
The following metadata are available in the setup of the mapfile:
WMS TAG Name: Abstract (WMS1.1.1, sect. 7.1.4.2)
Description: (Optional) A blurb of text providing more information about the WMS server.
WMS TAG Name: AccessConstraints (WMS1.1.1, sect. 7.1.4.2)
Description:(Optional) Access constraints information. Use the reserved word "none" if there are no access constraints.
WMS TAG Name: ContactAddress and family (WMS1.1.1, sect. 7.1.4.2)
Description: Optional contact address information. If provided then all six metadata items are required.
WMS TAG Name: ContactElectronicMailAddress (WMS1.1.1, sect. 7.1.4.2)
Description: Optional contact Email address.
WMS TAG Name: ContactFacsimileTelephone (WMS1.1.1, sect. 7.1.4.2)
Description: Optional contact facsimile telephone number.
WMS TAG Name: ContactInformation, ContactPerson, ContactOrganization, ContactPosition (WMS1.1.1, sect. 7.1.4.2)
Description: Optional contact information. If provided then all three metadata items are required.
WMS TAG Name: ContactVoiceTelephone (WMS1.1.1, sect. 7.1.4.2)
Description: Optional contact voice telephone number.
WMS TAG Name: Encoding
Description: Optional XML capabilities encoding type. The default is ISO-8859-1.
WMS TAG Name: Feature_info_mime_type
Description:
If not specified, then MapServer CAN process "text/html" MIME type if the GetFeatureInfo parameter INFO_FORMAT is set. In this case, the layer template is returned.
If set to "NONE", then MapServer will not process MIME type other than the default MIME type.
If set to something (except "NONE"), then MapServer will use the specified MIME type (whatever it is) if the GetFeatureInfo parameter INFO_FORMAT is set as well. In this case, the layer template is returned.
WMS TAG Name: Fees (WMS1.1.1, sect. 7.1.4.2)
Description: (Optional) Fees information. Use the reserved word "none" if there are no fees.
WMS TAG Name: Group_title (WMS1.1.1, sect. 7.1.4.1)
Description: (Optional) A human-readable name for the group that this layer belongs to. Only one layer for the group needs to contain wms_group_title, MapServer will find and use the value.
WMS TAG Name: KeywordList (WMS1.1.1, sect. 7.1.4.2)
Description: (Optional) A comma-separated list of keywords or keyword phrases to help catalog searching. As of WMS 1.1.0 no controlled vocabulary has been defined.
WMS TAG Name: OnlineResource (WMS1.1.1, sect. 6.2.2)
Description: (Recommended) The URL that will be used to access this WMS server. This value is used in the GetCapabilities response.
See Also: Sections "Setup a Mapfile / wms_onlineresource metadata" and More About the Online Resource URL above.
WMS TAG Name: BoundingBox (WMS1.1.1, sect. 6.5.6)
Description: (Optional) Used in the BoundingBox tag to provide info about spatial resolution of the data, values are in map projection units.
WMS TAG Name: SRS (WMS1.1.1, sect. 6.5.5)
Description: (Recommended) Contains a list of EPSG projection codes that should be advertized as being available for all layers in this server. The value can contain one or more EPSG:<code> pairs separated by spaces (e.g. "EPSG:4269 EPSG:4326") This value should be upper case (EPSG:42304.....not epsg:42304) to avoid problems with case sensitive platforms.
See Also: Section "Setup a Mapfile / Map PROJECTION and wms_srs metadata" above.
Same as wms_abstract in the Web Object .
WMS TAG Name: BoundingBox (WMS1.1.1, sect. 6.5.6)
Description: (Optional) Used for the layer's BoundingBox tag for cases where it is impossible (or very inefficient) for MapServer to probe the data source to figure its extents. The value for this metadata is "minx miny maxx maxy" separated by spaces, with the values in the layer's projection units. If wms_extent is provided then it has priority and MapServer will NOT try to read the source file's extents.
For Rasters served through WMS, MapServer can now use the wms_extent metadata parameter to register the image. If a .wld file cannot be found, MapServer will then look for the wms_extent metadata parameter and use the extents of the image and the size of the image for georegistration.
Same as wms_keywordlist in the Web Object .
WMS TAG Name: Layer (WMS1.1.1, sect. 7.1.4.6.3)
Description: (Optional) Set this metadata to "1" to indicate that the layer represents an area-filling coverage of space (e.g. a bathymetry and elevation layer). This should be taken by the client as a hint that this layer should be placed at the bottom of the stack of layers.
Same as wms_srs in the Web Object .
Same as wms_title in the Web Object .
| Q: | How can I find the EPSG code for my data's projection? |
| A: | If you know the parameters of your data's projection, then you can browse the "epsg" file that comes with PROJ4 and look for a projection definition that matches your data's projection. It's a simple text file and the EPSG code is inside brackets (<...>) at the beginning of every line. The "epsg" file is usually located in /usr/local/share/proj/ on Unix systems and in C:\PROJ\ or C:\PROJ\NAD in Windows systems (depending on the installation). |
| Q: | My WMS server produces the error "msProcessProjection(): no system list, errno: .." |
| A: | That's likely PROJ4 complaining that it cannot find the "epsg" projection definition file. Make sure you have installed PROJ 4.4.3 or more recent and that the "epsg" file is installed at the right location. On Unix it should be under /usr/local/share/proj/, and on Windows PROJ looks for it under C:\PROJ\ or C:\PROJ\NAD (depending on the installation). If you don't have the "epsg" file then you can get it as part of the PROJ4 distribution at http://www.remotesensing.org/proj/ or you can download it at http://www.maptools.org/dl/proj4-epsg.zip. |
| Q: | How do AUTO projections work? |
| A: | When a WMS client calls a WMS server with an auto projection, it has to specify the SRS in the form: AUTO: proj_id,unit_id,lon0,lat0 where:
When using an AUTO projection in WMS GetCapabilities, you include only the "AUTO:42003" string in your wms_srs metadata, you do not include the projection parameters. Those are added by the application (client) at runtime depending on the map view. For example:
NAME DEMO
...
WEB
...
METADATA
"wms_title" "WMS Demo Server"
"wms_onlineresource" "http://my.host.com/cgi-bin/mapserv?map=wms.map&"
"wms_srs" "AUTO:42001 AUTO:42002"
END
END
advertises the first two auto projections. |
Copyright (c) 2004, Jeff McKenna, DM Solutions Group Inc.
This documentation is covered by the same Open Source license as the MapServer software itself. See MapServer's License and Credits page for the complete text.
No liability for the contents of this document can be accepted. Use the concepts, examples and other content at your own risk. As this is a new edition of this document, there may be errors and inaccuracies that may be damaging to your system. Although this is highly unlikely, the author(s) do not take any responsibility for that: proceed with caution.
| Add a Comment |