**************************** MapServer for Windows (MS4W) **************************** :Author: Jeff McKenna, `Gateway Geomatics`_ :Contact: `Mailing List`_ :Revision: $Revision: 1.57 $ :Last Updated: $Date: 2008/12/03 01:00:02 $ .. _`Gateway Geomatics`: http://www.gatewaygeomatics.com/ .. _`Mailing List`: http://lists.maptools.org/mailman/listinfo/ms4w-users .. contents:: Table of Contents :depth: 3 :backlinks: top Introduction ============ Welcome to MS4W, the quick and easy installer for setting up MapServer For Windows and its accompanying applications (e.g., Chameleon, MapLab,etc.). The purpose of this package is to allow novice to advanced MapServer users to quickly install a MapServer development environment on their Windows systems. The reasons for needing to do this are diverse but, in general, this package supports: developers who want to get to a stable state quickly, trainers who need an easily-installed configuration identical across multiple installs, and novices who need help just getting all the needed bits and pieces together. Design ====== The MS4W package is designed to perform a full installation of Apache, PHP, MapServer CGI, MapScript (CSharp, Java, PHP, Python), and to provide the capability to install additional applications easily and quickly. The simplest way to do this on Windows is to provide a predetermined directory structure and force everything into that mold. The directory structure, while fixed within itself, is designed to be somewhat portable. While the ms4w_xxx.zip file needs to be installed at the root of a hard drive, it doesn't have to be the C:/ drive. Moving the package to the root of a different drive is simple - just copy it there. To move it to a subdirectory is more difficult - you'll need to search for /ms4w in all the files and replace it with your new path. The design also accommodates simple upgrades to the core package and to applications, without affecting the local configuration or the configuration of other installed applications. Contents ======== The following are included in the base package: - Apache version 2.2.10 - PHP version 5.2.6 - MapServer 5.2.1 CGI and MapScript (CSharp, Java, PHP, Python) - support GD 2.0.35, FreeType 2.1.10, GDAL/OGR 1.6.0RC2, PROJ, WMS/WFS, Flash, PDF, ECW3.1, PostGIS, GEOS, libcurl 7.15.1, FastCGI, AGG 2.4 - mapserver utilities - gdal/ogr utilities - proj.4 utilities - shp2tile utility - shapelib utilities - shpdiff utility - avce00 utilities - PHP_OGR Extension 1.1.1 - OWTChart 1.2.0 - DEMtools utilities MapServer Version Information ----------------------------- :: MapServer version 5.2.1 OUTPUT=GIF OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP OUTPUT=PDF OUTPUT=SWF OUTPUT=SVG SUPPORTS=PROJ SUPPORTS=AGG SUPPORTS=FREETYPE SUPPORTS=ICONV SUPPORTS=FRIBIDI SUPPORTS=WMS_SERVER SUPPORTS=WMS_CLIENT SUPPORTS=WFS_SERVER SUPPORTS=WFS_CLIENT SUPPORTS=WCS_SERVER SUPPORTS=SOS_SERVER SUPPORTS=FASTCGI SUPPORTS=THREADS SUPPORTS=GEOS SUPPORTS=RGBA_PNG INPUT=JPEG INPUT=POSTGIS INPUT=OGR INPUT=GDAL INPUT=SHAPEFILE MapServer Build Environment --------------------------- Compiled using Howard Butler's `MapServer buildkit`_ .. _`MapServer buildkit`: http://www.gatewaygeomatics.com/dl/buildkit/ Library Versions Used to build this version of MapServer: :: curl-7.15.1 expat-2.0.1 fcgi-2.4.0 fits-3.0.2 freetype-2.1.10 fribidi-0.19.1 gd-2.0.35 gdal-1.6.0 RC2 geos-2.2.3 gettext-0.13 hdf5 jbigkit-1.6 jpeg-6b libecwj2-3.3 libgeotiff-1.2.3 libiconv-1.9.1 libintl-0.11.5 libpng-1.2.8 libxml2-2.6.23.win32 mapserver-5.2.1 ming-0.2a mrsid-6.0.7.1407 mysql-5.0.18-win32 netcdf-3.6.1 PDFlib-Lite-6.0.2 php-5.2.6 postgresql-8.3.3 proj-4.6.1 Python-2.5.1 regex-0.12 sqlite3 SWIG-1.3.33 tiff-cvs (02/04/08) xerces-c-2.7.0 zlib-1.2.3 MapScript --------- - C# MapScript: compiled against .NET 1.1 runtime - Java MapScript: compiled against Java 1.6.0_01 - PHP MapScript: built for PHP 5 - Python MapScript: compiled against Python 2.5.1 *Perl, TCL, and Ruby MapScript are not in this MS4W release* OGR Formats Supported --------------------- See the `OGR formats page`_ for full driver descriptions. .. _OGR formats page: http://www.gdal.org/ogr/ogr_formats.html :: "ESRI Shapefile" (read/write) "MapInfo File" (read/write) "UK .NTF" (readonly) "SDTS" (readonly) "TIGER" (read/write) "S57" (read/write) "DGN" (read/write) "VRT" (readonly) "REC" (readonly) "Memory" (read/write) "BNA" (read/write) "CSV" (read/write) "GML" (read/write) "GPX" (read/write) "KML" (read/write) "GeoJSON" (read/write) "GMT" (read/write) "SQLite" (read/write) "ODBC" (read/write) "PGeo" (readonly) "PostgreSQL" (read/write) "MySQL" (read/write) "XPlane" (readonly) "AVCBin" (readonly) "AVCE00" (readonly) "Geoconcept" (read/write) Oracle - see `GDAL/OGR Plugins` section of this document to enable SDE - see `GDAL/OGR Plugins` section of this document to enable GDAL Formats Supported ---------------------- See the `GDAL formats page`_ for full driver descriptions. .. _GDAL formats page: http://www.gdal.org/formats_list.html :: VRT (rw+): Virtual Raster GTiff (rw+): GeoTIFF NITF (rw+): National Imagery Transmission Format RPFTOC (ro): Raster Product Format TOC format HFA (rw+): Erdas Imagine Images (.img) SAR_CEOS (ro): CEOS SAR Image CEOS (ro): CEOS Image JAXAPALSAR (ro): JAXA PALSAR Product Reader (Level 1.1/1.5) GFF (ro): Ground-based SAR Applications Testbed File Format (.gff) ELAS (rw+): ELAS AIG (ro): Arc/Info Binary Grid AAIGrid (rw): Arc/Info ASCII Grid SDTS (ro): SDTS Raster DTED (rw): DTED Elevation Raster PNG (rw): Portable Network Graphics JPEG (rw): JPEG JFIF MEM (rw+): In Memory Raster JDEM (ro): Japanese DEM (.mem) GIF (rw): Graphics Interchange Format (.gif) ESAT (ro): Envisat Image Format FITS (rw+): Flexible Image Transport System BSB (ro): Maptech BSB Nautical Charts XPM (rw): X11 PixMap Format BMP (rw+): MS Windows Device Independent Bitmap DIMAP (ro): SPOT DIMAP AirSAR (ro): AirSAR Polarimetric Image RS2 (ro): RadarSat 2 XML Product PCIDSK (rw+): PCIDSK Database File PCRaster (rw): PCRaster Raster File ILWIS (rw+): ILWIS Raster Map SGI (rw+): SGI Image File Format 1.0 SRTMHGT (rw): SRTMHGT File Format Leveller (rw+): Leveller heightfield Terragen (rw+): Terragen heightfield GMT (rw): GMT NetCDF Grid Format netCDF (rw): Network Common Data Format ISIS3 (ro): USGS Astrogeology ISIS cube (Version 3) ISIS2 (ro): USGS Astrogeology ISIS cube (Version 2) PDS (ro): NASA Planetary Data System ERS (rw+): ERMapper .ers Labelled ECW (rw): ERMapper Compressed Wavelets JP2ECW (rw+): ERMapper JPEG2000 L1B (ro): NOAA Polar Orbiter Level 1b Data Set FIT (rw): FIT Image GRIB (ro): GRIdded Binary (.grb) MrSID (ro): Multi-resolution Seamless Image Database (MrSID) JP2MrSID (ro): MrSID JPEG2000 RMF (rw+): Raster Matrix Format WCS (ro): OGC Web Coverage Service WMS (ro): OGC Web Map Service MSGN (ro): EUMETSAT Archive native (.nat) RST (rw+): Idrisi Raster A.1 INGR (rw+): Intergraph Raster GSAG (rw): Golden Software ASCII Grid (.grd) GSBG (rw+): Golden Software Binary Grid (.grd) GS7BG (ro): Golden Software 7 Binary Grid (.grd) COSAR (ro): COSAR Annotated Binary Matrix (TerraSAR-X) TSX (ro): TerraSAR-X Product COASP (ro): DRDC COASP SAR Processor Raster PNM (rw+): Portable Pixmap Format (netpbm) DOQ1 (ro): USGS DOQ (Old Style) DOQ2 (ro): USGS DOQ (New Style) ENVI (rw+): ENVI .hdr Labelled EHdr (rw+): ESRI .hdr Labelled GenBin (ro): Generic Binary (.hdr Labelled) PAux (rw+): PCI .aux Labelled MFF (rw+): Vexcel MFF Raster MFF2 (rw+): Vexcel MFF2 (HKV) Raster FujiBAS (ro): Fuji BAS Scanner Image GSC (ro): GSC Geogrid FAST (ro): EOSAT FAST Format BT (rw+): VTP .bt (Binary Terrain) 1.3 Format LAN (ro): Erdas .LAN/.GIS CPG (ro): Convair PolGASP IDA (rw+): Image Data and Analysis NDF (ro): NLAPS Data Format EIR (ro): Erdas Imagine Raw DIPEx (ro): DIPEx LCP (ro): FARSITE v.4 Landscape File (.lcp) RIK (ro): Swedish Grid RIK (.rik) USGSDEM (rw): USGS Optional ASCII DEM (and CDED) GXF (ro): GeoSoft Grid Exchange Format HTTP (ro): HTTP Fetching Wrapper HDF5 (ro): Hierarchical Data Format Release 5 HDF5Image (ro): HDF5 Dataset ADRG (rw+): ARC Digitized Raster Graphics BLX (rw): Magellan topo (.blx) SDE raster - see `GDAL/OGR Plugins` section of this document to enable Directory Structure ------------------- - ms4w/ - the main directory, assumed to be at the root of a drive, normally C: - ms4w/Apache - the Apache installation - ms4w/Apache/bin - the Apache binaries - ms4w/Apache/cgi-bin - the location of mapserv.exe and its supporting libraries, and php.ini, php.exe. - ms4w/Apache/cgi-bin/ignored-libmap - location of the libmap dll for Oracle (see the "Plugins" section of this document) - ms4w/Apache/cgi-bin/mapscript - location of CSharp, Java, and Python mapscript files - ms4w/Apache/conf - the Apache configuration files. These should not be modified. Place all application-specific and local httpd.conf files in /ms4w/httpd.d (see the README.txt in that directory) - ms4w/Apache/error - error files for Apache to use - ms4w/Apache/htdocs - the Apache Web root directory, you shouldn't install much in here except perhaps for testing. - ms4w/Apache/icons - icons used by Apache - ms4w/Apache/include - include directory for compiling against Apache - ms4w/Apache/lib - lib files for building against Apache - ms4w/Apache/logs - log files for Apache are stored here, this should be archived or cleaned every so often. - ms4w/Apache/manual - the Apache manual pages. - ms4w/Apache/modules - modules for Apache - ms4w/Apache/php - the PHP installation - ms4w/Apache/php/ext - location of phpmapscript dll - ms4w/Apache/proxy - apache proxy configurations, not used by MS4W - ms4w/Apache/specialplugins - location of the plugin dlls for MapServer (see the "Plugins" section of this document) - ms4w/apps - put all applications in subdirectories here. - ms4w/gdaldata - supporting files for GDAL data formats - ms4w/gdalplugins - place dlls here that are required for gdal plugins e.g. 'oci_OCI.dll' - ms4w/httpd.d - put all application-specific and local httpd.conf files here (see the README.txt in that directory) - ms4w/proj - an installation of PROJ.4 - the epsg file used is /ms4w/proj/nad/epsg - ms4w/python - associated python files, including gdal bindings and a simple test script - ms4w/tmp - temporary files go here. This should be cleaned regularly - ms4w/tmp/ms_tmp - temporary files that need to be Web-accessible go here (i.e. image files created by mapserver). This is available as /ms_tmp/ via URL. Normally this means that your MAP files would have an IMAGEPATH of /ms4w/tmp/ms_tmp/ and a IMAGEURL of /ms_tmp/ - ms4w/tools - contains useful tools such as the gdal/ogr utilities and mapserv utilities (note that before running these you must execute the /ms4w/setenv.bat script in your command window) How to Install MS4W =================== A. Upgrading from an older version of MS4W ------------------------------------------ If you already have MS4W installed please do the following: - open a DOS command window and execute the file '/ms4w/apache-uninstall.bat' at the commandline. This file will stop and uninstall your Apache service. You should see the following message flash in the command window: :: The "Apache MS4W Web Server" service is stopping. The "Apache MS4W Web Server" service has stopped. Removing the "Apache MS4W Web Server" service The "Apache MS4W Web Server" service has been removed successfully. - your old apache service has now been removed - make sure no files or other services point the your ms4w folder. If your browser is currently open and you are a viewing an ms4w page you will not be able to rename the ms4w folder. Therefore you must close all ms4w documents, all ms4w browser windows...make sure no running files point to the ms4w folder. - rename the old ms4w folder to something like 'ms4w-old' - extract the ms4w_xx.zip file to the root of a drive on your machine - if successful, you should have a new directory named 'ms4w' at the root of the drive you chose (e.g. C:/ms4w or D:/ms4w ). - follow the rest of the install instructions in /ms4w/README_INSTALL.txt to start apache... B. Extracting MS4W for the first time ------------------------------------- Please read through the following instructions before starting your installation. 1. To install the MS4W .zip file, use a compression program (e.g. WinZip) to extract the package at the root of a drive, e.g., drive C:\. If successful, you should have a new directory named 'ms4w' at the root of the drive you chose (e.g. C:/ms4w). 2. Start your MS4W Apache Web Server by running /ms4w/apache-install.bat (at the command line or by double-clicking it). This file installs Apache as a Windows service (called "Apache Web Server") so that it starts whenever your machine is restarted. When executed, a DOS window should pop up with the following message: :: Installing the Apache MS4W Web Server service The Apache MS4W Web Server service is successfully installed. Testing httpd.conf.... Errors reported here must be corrected before the service can be started. The Apache MS4W Web Server service is starting. The Apache MS4W Web Server service was started successfully. This means that Apache is running and installed as a service. **NOTE for Win95,98,ME users:** You will not be able to install Apache as a service, so instead you will have to manually start Apache each time, by clicking on /ms4w/Apache/bin/httpd.exe. An empty DOS window will open, which means Apache is running. To stop Apache you will have to close this empty DOS window. 3. To test that Apache is running properly, open your Web browser and find your local host Web service by entering one of the following URLs: :: http://localhost/ or http://127.0.0.1/ You should now see the main MS4W page in your Web browser. This gives you general information about your install along with configuration information. If this is your first time using MS4W it is very important that you review the listed "Features" installed within MS4W, and test them by selecting each link found on this page. 4. Technically, at this point, MS4W is installed! However, as you may have noticed from the MS4W main index.html page, there are no applications running. What this means is that there are no Web applications like MapLab or Chameleon found within MS4W's Web-accessible directory, /ms4w/apps/. The MS4W-configured Web applications can be found on http://maptools.org/ms4w/index.phtml?page=downloads.html as separate zip files. 5. To install these Web application into /ms4w/apps/ all that is required is to unzip the Web application compressed file at the same root directory as MS4W (e.g., C:\). Two things should happen when uncompressing this file. First, the Web application directory should appear within /ms4w/apps/. Second, a new httpd_*.conf file should be added to /ms4w/httpd.d/httpd_*.conf. (The /httpd.d/ directory contains Apache configuration files that define which files on your computer/server are Web-accessible. For each Web application that you install, a new configuration file will be found.) 6. The definitions of these Web-accessible directories are called Web Aliases. In order to activate a Web Alias you must restart Apache. To test your latest installed application, go to the MS4W main index.html page (i.e., http://localhost/). In the applications section you should now find a link to the application you just installed. Select the link to the recently installed application to see if it is configured correctly. Another option is find the Web Alias for your application and call it from your Web browser directly. For example, if you have installed the latest MS4W version of MapLab, the chances are the Web Alias is "maplab". To go to the MapLab index page, simply enter http://localhost/maplab/. Note: Applications with configuration files (e.g., MapLab and Chameleon) generally do not require any editing of their files in order to work. Just unzip to the appropriate driver root and restart Apache. WARNING: It is very possible that you may wish (but not encouraged!) to run multiple versions of the same product. For example, Maplab 2.0 (mapserver_36) vs. MapLab 2.1 (mapserver_4.0). When installing these ms4w MapLab application packages, you will notice when unzipping MapLab that the httpd_maplab.conf file found under ./ms4w/httpd.d/ will be overwritten by the MapLab you are currently installing. The reason for this is that the MapLab Alias stays the same from version to new version of MapLab. So, if you overwrite the httpd_maplab.conf when unzipping and then restart Apache, you will get the latest version of Maplab that you just installed. To run both MapLab simply follow the instructions in Step 7. 7. You also can create new Web Alias(es). To configure your own personal Web Alias(es), follow the instructions in /ms4w/httpd.d/README_HTTPD.txt C. Special Notes for Microsoft Vista ------------------------------------ In order to run the apache-install.bat file, you must do the following: 1. In Windows Explorer, goto the location of your cmd.exe file (C:/Windows/System32) 2. Right-click the cmd.exe executable and choose `Run as Administrator` 3. Navigate to your ms4w folder in the command prompt window and run apache-install.bat D. Plugins ---------- Oracle 10g ########## For OGR support of Oracle, MS4W >= 1.5.0 includes ogr_OCI.dll in /ms4w/gdalplugins/ignored/, which is built for Oracle 10g. Steps to Enable Oracle 10g Support in MS4W ****************************************** 1. Make sure you have Oracle 10g client software installed on your machine (the same machine that you are running MS4W on). 2. Replace the existing libmap.dll in /ms4w/Apache/cgi-bin/ with the one in the /ms4w/Apache/cgi-bin/ignored-libmap/oracle10g/ folder. 3. Move the ogr_OCI.dll plugin file up from /ms4w/gdalplugins/ignored/oracle-10g/ into /ms4w/gdalplugins/ If this is successful, executing the following at the commandline (after setting /ms4w/setenv.bat) "ogrinfo --formats" should list the OCI driver. 4. Restart Apache to be safe. 5. For mapfile configuration see http://mapserver.gis.umn.edu/docs/howto/oracle_spatial_howto SDE ### For OGR support of ESRI's ArcSDE, MS4W >= 1.5.0 includes ogr_SDE.dll in /ms4w/gdalplugins/ignored/, which is built for ArcSDE 9.1. Steps to Enable SDE 9.1 and 9.2 Support in MS4W's MapServer *********************************************************** The following steps apply as of MapServer 5.0 (including the betas and release candidates): 1. Make sure the ArcSDE SDK dlls for your SDE version are available on your machine (the same machine that you are running MS4W on). Here are some more specific 'rules' in terms of the ArcSDE SDK: - If you have to connect to both ArcSDE X.1 and X.2 servers, use the X.2 version of the ArcSDE SDK. You can usually connect to a X.1 version server with X.2 version client DLLs without ill effects. - To connect to X.2 servers, you *must* use X.2 versions of the ArcSDE SDK. - Do not use both the X.1 and X.2 versions of the plugins in the same MapServer map if you have to connect to both X.1 and X.2 version servers. Just use X.2. 2. Modify your SDE layer in your mapfile to use the CONNECTIONTYPE PLUGIN parameter and point to the appropriate plugin using the PLUGIN parameter: Example#1: SDE 9.1 layer :: LAYER ... #CONNECTIONTYPE SDE CONNECTIONTYPE PLUGIN CONNECTION "your server parameters" PLUGIN "C:/ms4w/Apache/specialplugins/msplugin_sde_91.dll" DATA "your data parameters" ... END # layer Example#2: SDE 9.2 layer :: LAYER ... #CONNECTIONTYPE SDE CONNECTIONTYPE PLUGIN CONNECTION "your server parameters" PLUGIN "C:/ms4w/Apache/specialplugins/msplugin_sde_92.dll" DATA "your data parameters" ... END # layer See the ArcSDE section of `MapServer's Vector Data Access`_ doc for help with the SDE CONNECTION and DATA parameters. .. _`MapServer's Vector Data Access`: http://mapserver.gis.umn.edu/docs/reference/vector_data/arcsde 3. Move the ogr_SDE.dll and gdal_SDE.dll plugin files up from /ms4w/gdalplugins/ignored/sde-x/ into /ms4w/gdalplugins/ If this is successful, executing the following at the commandline (after setting /ms4w/setenv.bat) "ogrinfo --formats" and "gdalinfo --formats" should list the SDE drivers. Note that you might want to add the ArcGIS location (such as C:\Program Files\ArcGIS\Bin) to your PATH environment variable. 4. Restart Apache to be safe. Microsoft SQL Server 2008 ######################### A read-only, native MapServer driver that connects to Microsoft SQL Server 2008's spatial capabilities is available in MS4W as of version 2.3.0. Steps to Enable SQL Server 2008 Support in MS4W's MapServer *********************************************************** 1. The plugin exists in /ms4w/Apache/specialplugins/msplugin_mssql2008.dll 2. Modify your SQL Server 2008 layer in your mapfile to use the CONNECTIONTYPE PLUGIN parameter and point to the appropriate plugin using the PLUGIN parameter. Use the CONNECTION parameter to specify the required connection parameters to access SQL Server, and use the DATA parameter to specify the table that holds the spatial information: :: LAYER ... CONNECTIONTYPE PLUGIN PLUGIN "C:/ms4w/Apache/specialplugins/msplugin_mssql2008.dll" CONNECTION "server=mysqlserver2008.com;uid=dbusername; pwd=dbpassword;database=Roads Database; Integrated Security=false" DATA "the_geom from roads" TYPE LINE STATUS ON CLASS ... END END 3. Test your layer, possibly by using the shp2img commandline utility with the '-all_debug 5' switch The associated RFC document with the original notes on this support is `RFC 38`_ .. _`RFC 38`: http://trac.osgeo.org/mapserver/browser/trunk/mapserver/rfc/ms-rfc-38.txt E. MapScript configuration -------------------------- MS4W >= 1.5.0 includes pre-built support files for csharp, java, and python mapscript. In order to make use of these, however, they must be installed and configured in the appropriate locations on your system. CSharp ###### 1. Files are located in ``/ms4w/Apache/cgi-bin/mapscript/csharp`` 2. See http://mapserver.gis.umn.edu/docs/howto/mapscriptcscompile for installation notes. Java #### 1. Files are located in ``/ms4w/Apache/cgi-bin/mapscript/java`` 2. See http://mapserver.gis.umn.edu/docs/howto/java_mapscript_Tomcat_55 for installation notes. Python ###### Obtaining Python **************** Obviously, in order to run Python mapscript, you need to have a python installed. The Python mapscript support files included in this distribution are built for Python 2.5.x; they will not work with earlier or later Python versions. Windows Python binaries can be obtained free of charge from ActiveState_ or the Python_ site. .. _ActiveState: http://www.activestate.com/Products/ActivePython/ .. _Python: http://www.python.org See the respective sites for Python installation information. Installing the Python Mapscript Support Files ********************************************* Quick and dirty (for use with ms4w only) ```````````````````````````````````````` 1. Unpack ``/ms4w/Apache/cgi-bin/mapscript/python/mapscript*win32.zip`` in a safe location 2. In the directory structure that results from the above step, navigate to ``\Python-2.5.1\Lib\site-packages`` 3. You should find three files there: - _mapscript.pyd - mapscript.py - mapscript.pyc 4. Copy the three files into the ``/ms4w/Apache/cgi-bin`` directory. 5. Place any python cgi scripts that you want to run under ms4w in the ``/ms4w/Apache/cgi-bin`` directory, and add a "shebang" line at the top of each script. See the section on `Configuring Apache to run Python scripts`_ below for shebang-line details. More robust (for system-wide access) ```````````````````````````````````` 1. Unpack ``/ms4w/Apache/cgi-bin/mapscript/python/mapscript*win32.zip`` in a safe location 2. In the directory structure that results from the above step, navigate to ``\Python-2.5.1\Lib\site-packages`` 3. You should find three files there: - _mapscript.pyd - mapscript.py - mapscript.pyc 4. Copy the three files into the site-packages directory of your Python 2.5.x installation (eg., ``C:\Python25\Lib\site-packages``) 5. Add ``:\ms4w\Apache\cgi-bin`` to your system's PYTHONPATH environment variable. Configuring Apache to Run Python Scripts **************************************** You have a couple of options here: via shebang lines ````````````````` This may be the preferred approach if you have multiple Python installations on your machine. Add a "shebang line" to the top of each python cgi script in ``/ms4w/apache/cgi-bin``. This line must be the first line in the script, and it must begin with #! followed by the path to your systems python executable. For example: :: #!c:/python25/python.exe -u The ``-u`` option shown above causes the script to use unbuffered output, which is generally what you need in web-serving contexts. via Apache directives ````````````````````` This approach obviates the need to edit every python script in your cgi-bin directory; however, it may be problematic if you have multiple Python installations. Add the following line to the end of ``ms4w/Apache/conf/httpd.conf``: :: ScriptInterpreterSource Registry You may also want to add these: :: SetEnv PYTHONUNBUFFERED 1 PassEnv PYTHONPATH The first of the above lines causes your python scripts to use unbuffered output (which you probably want), while the second passes the value of your system's PYTHONPATH environment variable through to Apache's environment (if set). Testing the Configuration ************************* Follow these steps to test your Python MapScript installation: 1. Move the file ``/ms4w/python/test-cgi-mapscript.py`` into the ``/ms4w/Apache/cgi-bin/`` folder. 2. Open the file in a text editor. 3. Edit the first line of that script to point to your proper Python path. 4. In your web browser goto http://127.0.0.1/cgi-bin/test-cgi-mapscript.py 5. The script tests that the Python CGI is working, and that the mapscript module can be successfully imported. If successful you will see an HTML page listing several environment settings on your machine, as well a list of the Python MapScript module attributes at the bottom of the page. Python Troubleshooting: - If you get an Internal Server Error check the Apache logs for info. - Make sure your script points to a valid Python installation path. - Make sure you are using a recent Python version (containing the cgitb module). F. FastCGI ---------- Starting with MS4W 2.2.8, MapServer is built with FastCGI support, and the required Apache module (mod_fcgid) is loaded by default. In order to use FastCGI you must do the following: 1. Download and install the `Visual C++ 2008 Redistributable Package`_ .. _`Visual C++ 2008 Redistributable Package`: http://www.microsoft.com/downloads/details.aspx?FamilyID=9B2DA534-3E03-4391-8A4D-074B9F2BC1BF&displaylang=en 2. Open /Apache/conf/httpd.conf in a text editor 3. Uncomment line#127, such as: :: LoadModule fcgid_module modules/mod_fcgid.so 4. At the bottom of the file you will see a commented "" section. Uncomment each line and modify the paths for your local paths, such as: :: DefaultInitEnv PROJ_LIB "c:/ms4w/proj/nad/" DefaultInitEnv PATH "c:/ms4w/Apache/cgi-bin; c:/WINDOWS/system32;c:/WINDOWS;c:/WINDOWS/System32/Wbem;" DefaultInitEnv windir "c:/WINDOWS" DefaultInitEnv SystemRoot "c:/WINDOWS" DefaultInitEnv SystemDrive "c:" DefaultInitEnv GDAL_DATA "c:/ms4w/gdaldata" DefaultInitEnv GDAL_DRIVER_PATH "c:/ms4w/gdalplugins" DefaultInitEnv TMP "c:/ms4w/tmp" DefaultInitEnv TEMP "c:/ms4w/tmp" 5. You can also add FastCGI directives (listed on the `mod_fcgid`_ page) to that section, such as: :: IPCCommTimeout 60 IdleTimeout 60 DefaultMinClassProcessCount 2 DefaultMaxClassProcessCount 20 DefaultInitEnv PROJ_LIB "c:/ms4w/proj/nad/" DefaultInitEnv PATH "c:/ms4w/Apache/cgi-bin; c:/WINDOWS/system32;c:/WINDOWS;c:/WINDOWS/System32/Wbem;" DefaultInitEnv windir "c:/WINDOWS" DefaultInitEnv SystemRoot "c:/WINDOWS" DefaultInitEnv SystemDrive "c:" DefaultInitEnv GDAL_DATA "c:/ms4w/gdaldata" DefaultInitEnv GDAL_DRIVER_PATH "c:/ms4w/gdalplugins" DefaultInitEnv TMP "c:/ms4w/tmp" DefaultInitEnv TEMP "c:/ms4w/tmp" .. _`mod_fcgid`: http://fastcgi.coremail.cn/doc.htm 6. Save the file and restart apache (execute /ms4w/apache-restart.bat) 7. Change your CGI application to point to "/fcgi-bin/mapserv.exe" instead of the usual "/cgi-bin/mapserv.exe" 8. Add the following parameter to your layer for which you want this FastCGI connection: :: PROCESSING "CLOSE_CONNECTION=DEFER" 9. Try the application. If successful you should see the "mapserv.exe" process in the Windows Task Manager remain open while the user interacts with your application. Notes: * in testing this was successful with PostgreSQL 8.3.1 / PostGIS 1.3.3, but unsuccessful with Oracle 10.2.0.1.0 (Apache logs: "mod_fcgid: get overlap result error") * general MapServer and FastCGI notes can be found in the `FastCGI Howto`_. .. _`FastCGI Howto`: http://mapserver.gis.umn.edu/docs/howto/fastcgi G. Troubleshooting ------------------ **Warning: dl(): Unable to load dynamic library '/ms4w/Apache/php/extensions/php_mapscript.dll'** 1. Verify that the dll in question exists in the specified location (/ms4w/Apache/php/extensions/). If this dll is not in that location, you might have to modify the application to point to a different version of the dll (e.g. you might have *php_mapscript.dll* in the extensions directory, and your application might be configured for *php_mapscript_48.dll* which is not in the extensions directory). 2. This php_mapscript dll requires several other dlls, and the problem may be that one is missing on your system. In order to hopefully get more information on what dll is missing, go to a command prompt, and do the following: :: cd ms4w\Apache\cgi-bin php C:/ms4w/Apache/htdocs/phpinfo_mapscript.php A windows error window should open with a message like: :: The dynamic link library ***** could not be found in the specified path... Locate this missing dll and copy it either to /ms4w/Apache/cgi-bin/ or your system32 folder. 3. If you are still unsure what dll is causing this *unable to load dynamic library* error, a useful utility to find what associated dlls are missing on your system is `Dependency Walker`_. Download the utility, execute the exe, and open your php_mapscript dll. .. _`Dependency Walker`: http://www.dependencywalker.com/ **The dynamic link library MSVCP71.dll could not be found in the specified path...** This is a microsoft runtime library that is apparently not on all Windows systems by default. Download the dll (possibly from `here`_) and copy it to your System32 directory. .. _`here`: http://www.dll-files.com/dllindex/dll-files.shtml?msvcp71 **Clicking on apache-install.bat flashes a DOS window and does not install the service** To see the exact error message, open a Command window, and execute the 'apache-install.bat' file from a DOS prompt. :: cd ms4w apache-install.bat **Only one usage of each socket address (protocol/network address/port) is normally permitted. : make_sock: could not bind to address 0.0.0.0:80 no listening sockets available, shutting down** Apache with MS4W is configured to use port 80. Your system might be already using this port (IIS could cause this for example). If you want to change the port that Apache uses modify the following file: :: /ms4w/Apache/conf/httpd.conf line 120: Listen 80 `TCPView`_ is an example of shareware that lets you see how the ports on your machine are being used. .. _`TCPView`: http://www.sysinternals.com/Utilities/TcpView.html **The procedure entry point xxxx could not be located in the dynamic link library xxx.dll** Make sure that MapServer (or the utility that you are trying to use) is actually using the 'xxx.dll' file that is part of the MS4W package. You could be experiencing 'dll hell' (http://en.wikipedia.org/wiki/DLL_hell) where MS4W is actually finding an older dll on your system. Try renaming the other dll(s) of the same name, keeping the one in MS4W as is, and retrying your application/command. **Other Problems...** 1. Search the `mailing list archives`_ to see if someone has encountered/solved your same issue. .. _`mailing list archives`: http://lists.maptools.org/search.phtml?config=ms4w-users 2. If your issue has not been brought up on the mailing list and dealt with, submit a question to the `MS4W mailing list`_. Include the steps to reproduce your problem, and state your exact error message. Also specify which version of MS4W you are using. .. _`MS4W mailing list`: http://lists.maptools.org/mailman/listinfo/ms4w-users H. Modifying MS4W for an Installation not at the Drive Root ----------------------------------------------------------- Do the following steps in a text editor: 1. Open /ms4w/Apache/conf/httpd.conf and search for "/ms4w/" and replace with your new path from your drive root (such as "/Temp/ms4w/") 2. Open /ms4w/Apache/cgi-bin/php.ini and search for "/ms4w/" and replace with your new path from your drive root (such as "/Temp/ms4w/") 3. Open all files in /ms4w/httpd.d and search for "/ms4w/" and replace with your new path from your drive root (such as "/Temp/ms4w/") 4. Open /ms4w/setenv.bat and search for "/ms4w/" and replace with your new path from your drive root (such as "/Temp/ms4w/") 5. Configure your add-on packages. Using Chameleon as an example: Open /ms4w/apps/chameleon/config/chameleon.xml and search for "/ms4w/" and replace with your new path from your drive root (such as "/Temp/ms4w/") Recommendation: avoid installing MS4W in a path that contains spaces I. Installing the MS4W MapServer Binaries in Other Environments --------------------------------------------------------------- The following instructions will help non-MS4W users who want to only use the MapServer binaries included in MS4W: 1. Download and extract the MS4W base package locally from `MapTools`_. .. _`MapTools`: http://www.maptools.org/ms4w/index.phtml?page=downloads.html 2. Do not install the Apache service (apache-install.bat) 3. Copy the following necessary files from the `/ms4w/apache/cgi-bin/` directory into your desired cgi-bin directory: :: cfitsio.dll fdftk.dll fribidi.dll gdal16.dll gds32.dll geos_c.dll geotiff.dll hdf5dll.dll iconv.dll jbig1.dll libcurl.dll libeay32.dll libecwj2.dll libexpat.dll libfcgi.dll libmap.dll libmcrypt.dll libmhash.dll libmysql.dll libpq.dll libswish-e.dll libtiff.dll libxml2.dll lti_dsdk_cdll.dll lti_dsdk_dll.dll mapserv.exe msql.dll msvcp71.dll msvcr71.dll netcdf.dll ntwdblib.dll pdflib.dll proj.dll shapelib.dll sqlite3.dll ssleay32.dll szlibdll.dll xerces-c_2_7.dll zlib1.dll 4. For PHP/Mapscript, goto `/ms4w/Apache/php/ext/` and copy the `php_mapscript.dll` file into your own PHP extensions directory. Csharp, Java, and Python mapscript files can be found in `/ms4w/Apache/cgi-bin/mapscript/` 5. For the commandline utilities that come with MS4W (mapserv, gdal, etc.) copy all of the `.exe` files from `/ms4w/tools/` to a desired location, but be aware that these utilities use dlls that were installed in the cgi-bin directory. Therefore you must add your cgi-bin directory into your Windows PATH environment variable before running the utilities. 6. Microsoft IIS users should refer to the `IIS Howto`_ for MapServer. .. _`IIS Howto`: http://mapserver.gis.umn.edu/docs/howto/setupiis Password Protection Configuration for Applications ================================================== The following section explains how to add password authentication to your MS4W application. However there are many other possible settings in Apache for this, so please consult the Apache HTTP Server documentation. Here are the minimal steps for password protection: 1. Modify your application's httpd_xxx.conf file, so that "AllowOverride None" is replaced with "AllowOverride AuthConfig", such as: :: Alias /gmap/ "/ms4w/apps/gmap/htdocs/" AllowOverride AuthConfig Options Indexes FollowSymLinks Multiviews Order allow,deny Allow from all 2. Create a password file. - open a DOS command window, and go to Apache's bin directory - enter the following (replace "jeff" with the username you want to create, press ENTER and you will be prompted for a password to create): :: C:/ms4w/Apache/bin> htpasswd -c htpasswd.txt jeff 3. Create the htaccess file. - create a file in your application directory (/ms4w/apps/gmap/htdocs/ in this example) named '.htaccess' - the file should contain (you can modify it however you wish though): :: AuthType Basic AuthUserFile C:/ms4w/Apache/bin/htpasswd.txt AuthName "Password Required" require valid-user 4. Restart Apache - run /ms4w/apache-restart.bat 5. Access your application in a web browser. *Troubleshooting:* - some Windows versions may have difficulty with the '.htaccess' filename, so you might try naming it something else, but you would have to modify Apache's httpd.conf file (/ms4w/Apache/conf/httpd.conf) and add your filename, such as: :: AccessFileName .htaccess yourfilename 'htaccess.acl' is recommended, such as: :: AccessFileName .htaccess htaccess.acl - a good reference is http://sniptools.com/tutorials/windows-apache-and-htaccess-authentication MS4W Applications ================= The following applications come with a pre-configured install package for MS4W. Go to http://www.maptools.org/ms4w/index.phtml?page=downloads.html to find the desired package, and extract the packages to the MS4W root (e.g. if you installed in C:\ then extract at C:\, and if you installed the base in C:\Program Files then extract the packages to C:\Program Files). 1) ArcIMS Emulator 2) Chameleon 3) dBox MapServer 4) FIST - Flexible Internet Spatial Template 5) GeoMOOSE 6) ka-Map 7) MapBender 8) MapServer Itasca Demo Application 9) OGC Workshop 10) OpenLayers 11) GMap Sample PHP/MapScript Application 12) phpPgAdmin 13) p.mapper Additional Support ================== General questions and comments should be sent to the MS4W mailing list, which you can join at: http://lists.maptools.org/mailman/listinfo/ms4w-users Requests for changes and enhancements to MS4W should be filed in the MS4W `tracker`_. .. _`tracker`: http://www.maptools.org/bugzilla/query.cgi Custom support is also available from `Gateway Geomatics`_. About this Document =================== Copyright/Licensing Information ------------------------------- Copyright (c) 2003-2008, Jeff McKenna, Gateway Geomatics. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Portions of this computer program are copyright (c) 1995-2005 LizardTech, Inc. All rights reserved. MrSID is protected by U.S. Patent No. 5,710,835. Foreign Patents Pending.