Serverconfig.ini and Webconfig.ini Documentation and Tuning
Revision History
| Revision | Date | Author | Comment |
| 0.7 | August 25, 2011 | Christine Bao | Add FDOConnectionTimeoutCustom information |
| 0.6 | August 15, 2011 | Christine Bao | Update DB Environment settings |
| 0.5 | July 7, 2011 | Bruce Dechant | Updated port settings |
| 0.4 | December 9, 2010 | Bruce Dechant | Added SessionRepositoriesConfig and SessionRepositoriesLimit information |
| 0.3 | December 6, 2010 | Bruce Dechant | Added PreCacheMaps information |
| 0.2 | July 2, 2010 | Trevor Wekel | Add some tuning considerations |
| 0.1 | May 10, 2010 | Trevor Wekel | Initial pass at documentation |
Table of Contents
- Overview
-
Serverconfig.ini
- Overview
- [GeneralProperties] Section
- [AdministrativeConnectionProperties] Section
- [ClientConnectionProperties] Section
- [SiteConnectionProperties] Section
- [HostProperties] Section
- [DrawingServiceProperties] Section
- [FeatureServiceProperties] Section
- [MappingServiceProperties] Section
- [RenderingServiceProperties] Section
- [ResourceServiceProperties] Section
- [SiteServiceProperties] Section
- [TileServiceProperties] Section
- [AccessLogProperties] Section
- [AdminLogProperties] Section
- [AuthenticationLogProperties] Section
- [ErrorLogProperties] Section
- [SessionLogProperties] Section
- [TraceLogProperties] Section
- [FontAliases] Section
- [UnmanagedDataMappings] Section
- [DBEnvironmentProperties] Section
- Webconfig.ini
Overview
This document describes the parameters and provides parameter tuning tips for serverconfig.ini and webconfig.ini.
Tuning Quick Links
Serverconfig.ini
| Parameter | Description |
| Server max connections | Tuning the # of Web Tier TCP/IP connections accepted |
| Server request queue size | Tuning the size of the Server request queues |
| Server thread pool size | Tuning the size of the Server thread pools |
| Server cache size | Tuning schema and class definition cache |
| Server connection pooling excluded providers | Tuning connection pooling excluded FDO Providers |
| Server data connection pool size | Tuning FDO provider data connection pooling |
| Server "per provider" data connection pool size | Tuning per provider FDO data connections |
| RepositoryCheckpointsTimerInterval | Tuning resource repository checkpoint interval |
| SessionTimeout | Tuning session repository timeout for idle sessions |
| SessionTimerInterval | Tuning session repository timer interval |
Webconfig.ini
| Parameter | Description |
| Failover retry time | Tuning failover retry between Server and Web Tier |
| Web Tier max connections | Tuning TCP/IP connections between Server and Web Tier |
Common Validation Information
String Properties
| Property Type | Range of String Length | Reserved Characters |
| File Name | 0 < Length <= 128 | \/:*?"<>| |
| Folder Name | 0 < Length <= 128 | \/:*?"<>| |
| Log Parameters | 0 < Length <= 1024 | |
| Password | 0 < Length <= 64 | \t\r\n\v\f |
| Path | 0 < Length <= 255 | *?"<>| |
Numeric Properties
| Property Type | Range of String Length |
| Port Number | 0 < Value <= 65535 |
Serverconfig.ini
Overview
Serverconfig.ini controls various aspects of the MapGuide Server process. It is typically located in C:\Program Files\OSGeo\MapGuide\Server\bin or /usr/local/mapguideopensource/server/bin.
[GeneralProperties] Section
| Property Name | Supported In | Restrictions | Description |
| ConnectionTimeout | < Value <= 86400 | Time duration in seconds for when an idle connection is dropped | |
| ConnectionTimerInterval | 0 < Value <= 2147483647 | Time interval in seconds for when the server checks for idle connections | |
| DefaultMessageLocale | Length = 2 | ISO 639-1 name for the message locale | |
| DisplayName | 0 <= Length <= 255 Reserved Characters: \/:*?"<>| | Display name of the server | |
| FdoPath | Path where FDO is installed | ||
| LicenseServerPath | The path to the License server (not used by MapGuide Open Source) | ||
| Locale | 0 <= Length <= 255 | The server's locale. | |
| LogsDelimiter | Delimiter that separates the data fields in the log files | ||
| LogsDetail | Level of logging detail per service | ||
| LogsPath | Path where log files are stored | ||
| MachineIp | 0 < Length <= 255 | IP address of the server | |
| MaxLogFileSize | 0 < Value <= 2000000 | Max size allowed for the log files in kilobytes (KB) | |
| MaxLogFileSizeEnabled | 0 = max size disabled, 1 = max size enabled | ||
| PreCacheMaps | The list of maps to precache at server startup. Map resource name(s) separated by "," | ||
| Renderer | Image renderer to use (GD or AGG) | ||
| ResourcesPath | Path where the localization resource files are stored | ||
| SerialNumber | 0 <= Length <= 12 | The MapGuide Server serial number (not used by MapGuide Open Source) | |
| TcpIpMtu | 0 < Value <= 65535 | TCP/IP maximum transmission unit | |
| TempPath | Path where the temporary files are stored | ||
| WfsDocumentPath | Document path location for WFS documents | ||
| WmsDocumentPath | Document path location for WMS documents |
Locale Parameter
The server's locale. If left blank it will default to the operating system locale
Format: lang[_country_region.code_page]
Example (Windows): English_United States.1252
Example (Linux): en_US.iso88591
LogsDetail Parameter
Level of logging detail per service.
- 0 - Errors without parameters (default)
- 1 - Warnings and Errors with parameters
- 2 - Trace, Warnings, and Errors
- 3 - Internal Trace, Trace, Warnings, and Errors
Service keys: ResourceService, DrawingService, FeatureService, MappingService, RenderingService, TileService, KmlService, ServerAdminService, SiteService
Example: MappingService:3,FeatureService:1
[AdministrativeConnectionProperties] Section
| Property Name | Supported In | Restrictions | Description |
| 0 <= Length <= 255 | Server administrator's email address | ||
| MaxConnections | 0 < Value <= 1024 | Max # of open administration connections | |
| Port | Port to use for administration operations. WARNING: If you change the port # here you must also change the corresponding port # in webconfig.ini | ||
| QueueSize | 0 < Value <= 1024 | Max # of administration operations to queue | |
| ThreadPoolSize | 0 < Value <= 1024 | # of threads available for processing administration operations |
MaxConnections
MaxConnections determines the maximum number of web tier connections the server will accept. For MapGuide 2.1 and earlier on Windows, the total number of connections (administrative + client + site) must be no greater than 62 connections. On the 63rd connection attempt, the server will become unresponsive. For MapGuide 2.2 on Windows and all versions of MapGuide on Linux, the supported connection limit is greater than 500 connections.
To fully utilize all cores on a MapGuide server machine, there should be 1 administrative, 3 client, and 2 site connections per core. Assigning additional connections may reduce request queue lengths and better utilize server resources if longer delay features sources like WMS, WFS, and databases are used. For local on-disk feature sources like SDF and SHP, the 1/3/2 per core listed above will typically be sufficient.
QueueSize
The request queue size should be set to at leat MaxConnections - ThreadPoolSize. Setting the queue size too low could lead to request loss under heavy load.
ThreadPoolSize
To fully utilize all cores on a MapGuide server machine, there should be 1 administrative, 3 client, and 2 site threads available per core. Increasing the thread pool size further may reduce request queue lengths and better utilize server resources if longer delay features sources like WMS, WFS, and databases are used. For local on-disk feature sources like SDF and SHP, the 1/3/2 per core listed above will typically be sufficient.
[ClientConnectionProperties] Section
| Property Name | Supported In | Restrictions | Description |
| MaxConnections | 0 < Value <= 1024 | Max # of open client connections | |
| Port | Port to use for client operations. WARNING: If you change the port # here you must also change the corresponding port # in webconfig.ini | ||
| QueueSize | 0 < Value <= 1024 | Max # of client operations to queue | |
| ThreadPoolSize | 0 < Value <= 1024 | # of threads available for processing client operations |
[SiteConnectionProperties] Section
| Property Name | Supported In | Restrictions | Description |
| IpAddress | 0 < Length <= 255 | IP address of site server | |
| MaxConnections | 0 < Value <= 1024 | Max # of open site connections | |
| Port | Port to use for site operations. WARNING: If you change the port # here you must also change the corresponding port # in webconfig.ini | ||
| QueueSize | 0 < Value <= 1024 | Max # of site operations to queue | |
| ThreadPoolSize | 0 < Value <= 1024 | # of threads available for processing site operations |
[HostProperties] Section
| Property Name | Supported In | Restrictions | Description |
| DrawingService | 0 = service unavailable, 1 = service available | ||
| FeatureService | 0 = service unavailable, 1 = service available | ||
| KmlService | 0 = service unavailable, 1 = service available | ||
| MappingService | 0 = service unavailable, 1 = service available | ||
| RenderingService | 0 = service unavailable, 1 = service available | ||
| ResourceService | 0 = service unavailable, 1 = service available | ||
| SiteService | 0 = service unavailable, 1 = service available | ||
| TileService | 0 = service unavailable, 1 = service available |
[DrawingServiceProperties] Section
[FeatureServiceProperties] Section
| Property Name | Supported In | Restrictions | Description |
| CacheSize | 0 < Value <= 5000 | Max # of internal data objects to cache (schemas, classes, etc...) | |
| CacheTimeLimit | 0 < Value <= 2147483647 | Time duration in seconds for how long to cache the internal data objects | |
| CacheTimerInterval | 0 < Value <= 2147483647 | Time interval in seconds for when the server checks for expired cache entries | |
| DataCacheSize | 0 < Value <= 2147483647 | Max # of features to fetch | |
| DataConnectionPoolEnabled | 0 = disabled, 1 = enabled | FDO connection pooling | |
| DataConnectionPoolExcludedProviders | 0 <= Length <= 1024 Value = provider name(s) separated by "," Example: OSGeo.SDF,OSGeo.SHP | The list of providers to exclude from connection pooling. | |
| DataConnectionPoolSize | 1 < Value <= 1024 | Default # of FDO connections to cache per provider | |
| DataConnectionPoolSizeCustom | 0 <= Length <= 1024 Example: OSGeo.SDF:10,OSGeo.SHP:10 | Custom # of FDO connections to cache for specified provider | |
| DataConnectionTimeout | 0 < Value <= 2147483647 | Time duration in seconds for when an idle FDO connection is dropped | |
| DataConnectionTimerInterval | 0 < Value <= 2147483647 | Time interval in seconds for when the server checks for idle FDO connections | |
| JoinQueryBatchSize | 1 < Value <= 10000 | Join query batch size | |
| DataTransactionTimeout | 0 < Value <= 1800 | Time duration in seconds for when an idle FDO transaction is dropped | |
| DataTransactionTimerInterval | 0 < Value <= 1800 | Time interval in seconds for when the server checks for idle FDO transactions | |
| FDOConnectionTimeoutCustom | 0 <= Length <= 1024 | Time duration in seconds for an FDO connection per provider |
CacheSize
The MapGuide Server uses schema and class definition information in many requests. Caching this information locally increases server throughput and increases the memory footprint. CacheSize controls how many objects the server will cache. If sufficient memory is available, the CacheSize should be set to the total number of feature classes visible from all feature sources.
DataConnectionPoolExcludedProviders
By default, SDF data sources do not use pooled connections. This allows read/write operations to occur. Some performance improvement can be obtained by enabling connection pooling for SDF and SHP. Note: Turning on connection pooling for SDF will make SDF unsuitable for FDO update operations. If temporary layers are constructed using SDFs, connection pooling must be disabled for SDF.
DataConnectionPoolSize
Pooled connections allows the MapGuide Server to reuse existing connections to FDO feature sources. Database connections are created once and reused for multiple requests. Typically, two connections per core is sufficient to obtain full utilization of the cores on the MapGuide Server. Please note: Many FDO providers maintain schema for each connection. This increases the memory footprint as more connections are opened.
DataConnectionPoolSizeCustom
Pooled connections can also be set on a per-provider basis. This can be used to increase the connection pool for specific providers, like databases, while leaving the other providers alone. See DataConnectionPoolSize for tuning considerations.
FDOConnectionTimeoutCustom ===#ServerFDOConnectionTimeoutCustom Custom
FDOConnectionTimeoutCustom can be used to set the timeout value for FDO providers which supports ConnectionTimeout capability. For example, if WMS server sometimes is available and want it quick return when meet error, this setting can be used to set a lower value. The format is like OSGeo.WMS:120,OSGeo.WFS.100
[MappingServiceProperties] Section
| Property Name | Supported In | Restrictions | Description |
| LegendFont | 0 < Length <= 255 | Font to use when rendering legend elements |
[RenderingServiceProperties] Section
| Property Name | Supported In | Restrictions | Description |
| TileExtentOffset | 0.0 <= Value <= 1.0 | Max request extent offset to use when requesting features for a tile, specified as a factor of the tile size | |
| RasterGridSize | 0 < Value <= 2147483647 | Size of raster re-projection grid in pixels | |
| MinRasterGridSize | 0 < Value <= 2147483647 | Minimum size of raster re-projection grid in pixels. This should be less than RasterGridSize. | |
| RasterGridSizeOverrideRatio | 0.0 <= Value <= 1.0 | If the RasterGridSize is larger than the image's height or width multiplied by the RasterGridSizeOverrideRatio, then the RasterGridSize is overridden with this value. Set to 0 or 1 to disable the override. | |
| RasterGridSizeForPlot | Size of raster re-projection grid in pixels for plot | ||
| MinRasterGridSizeForPlot | Minimum size of raster re-projection grid in pixels for plot. This must be less than RasterGridSizeForPlot. | ||
| RasterGridSizeOverrideRatioForPlot | If the RasterGridSizeForPlot is larger than the image's height or width multiplied by the RasterGridSizeOverrideRatioForPlot, then the RasterGridSizeForPlot is overridden with this value. Set to 0 or 1 to disable the override. | ||
| RenderSelectionBatchSize | The batch size to use when rendering a selection | ||
| ClampPoints | 0 = false and 1 = true | Specifies whether point coordinates are clamped to integer values before passing them to the AGG renderer (experimental) | |
| GeneralizeData | 0 = false and 1 = true | Specifies whether feature geometry is generalized before being rendered (experimental) |
[ResourceServiceProperties] Section
| Property Name | Supported In | Restrictions | Description |
| LibraryRepositoryPath | Path where the Library repository is stored | ||
| LibraryResourceDataFilePath | Path where the Library resource data files are stored | ||
| PackagesPath | Path where the resource packages can be found | ||
| RepositoryCheckpointsTimerInterval | 0 < Value <= 2147483647 | Time duration in seconds for when the server performs checkpoints for all the repositories | |
| ResourceChangeTimerInterval | 0 < Value <= 2147483647 | Time duration in seconds for when the server dispatches resource change notifications | |
| ResourceDataFileTrashFolderName | Folder where the repository trash files are stored | ||
| ResourcePermissionCacheSize | 0 <= Value <= 2147483647 | Max # of resources with permission information to be cached | |
| ResourceSchemaFilePath | Path where the resource schema files are stored | ||
| SessionRepositoriesConfig | SingleFile or FilePerSession | Sets whether to use a single file session repository or a session repository file per session. | |
| SessionRepositoriesLimit | The total number of active session files allowed. This setting only works when FilePerSession is used. | ||
| SessionRepositoryPath | Path where the Session repository is stored | ||
| SessionResourceDataFilePath | Path where the Session resource data files are stored | ||
| SiteRepositoryPath | Path where the Site repository is stored |
RepositoryCheckpointsTimerInterval
The repository checkpoints timer interval determines the time between successive Resource Service database checkpoints. While a checkpoint occurs, all database writes are suspended. This can lead to freezes in client UI interaction as the Web Tier waits for the Session Repository to accept writes. Reducing the checkpoint interval will increase the number of freezes that occcur in a given time interval and will also reduce the time per freeze. If the database checkpoint takes too long, some operations will timeout and users may experience unexpected behaviour. Please note: Very large concurrent user loads are needed before checkpoint freezes become noticeable.
[SiteServiceProperties] Section
| Property Name | Supported In | Restrictions | Description |
| SessionTimeout | 0 < Value <= 86400 | Time duration in seconds for when an idle session is expired | |
| SessionTimerInterval | 0 < Value <= 2147483647 | ime interval in seconds for when the server checks for idle sessions |
SessionTimeout
The session timeout determines the maximum idle time for a session. Once the idle time has been reached, the session will be deleted from the session repository. The MapGuide Server keeps a portion of the session repository in memory and flushes least used pages to disk. A shorter idle time will delete sessions more rapidly and reduce page flushing. The page flush occurs during repository checkpointing.
SessionTimerInterval
The session timer interval controls how often the session repository is checked for idle sessions. This value should be set to 1/2 or 1/3rd of the session timeout to ensure that ide sessions are removed on a regular basis.
[TileServiceProperties] Section
| Property Name | Supported In | Restrictions | Description |
| RenderOnly | 0 = false and 1 = true | Renders the tile only | |
| TileCachePath | Root path of the image tile cache | ||
| TileColumnsPerFolder | 0 < Value <= 1000 | Number of columns of tiles per folder | |
| TileRowsPerFolder | 0 < Value <= 1000 | Number of rows of tiles per folder | |
| !DefaultTileSizeX | 50 < value <= 10000 | Width of generated tiles in pixels | |
| !DefaultTileSizeY | 50 < value <= 10000 | Height of generated tiles in pixels | |
| ImageFormat | PNG, PNG8, GIF or JPG | Image format for generated tiles |
[AccessLogProperties] Section
| Property Name | Supported In | Restrictions | Description |
| Enabled | 0 = log disabled, 1 = log enabled | ||
| Filename | Name of the log file | ||
| Parameters | Log parameters, eg. CLIENT,CLIENTIP,USER,OPID |
[AdminLogProperties] Section
| Property Name | Supported In | Restrictions | Description |
| Enabled | 0 = log disabled, 1 = log enabled | ||
| Filename | Name of the log file | ||
| Parameters | Log parameters, eg. CLIENT,CLIENTIP,USER,OPID |
[AuthenticationLogProperties] Section
| Property Name | Supported In | Restrictions | Description |
| Enabled | 0 = log disabled, 1 = log enabled | ||
| Filename | Name of the log file | ||
| Parameters | Log parameters, eg. CLIENT,CLIENTIP,USER |
[ErrorLogProperties] Section
| Property Name | Supported In | Restrictions | Description |
| Enabled | 0 = log disabled, 1 = log enabled | ||
| Filename | Name of the log file | ||
| Parameters | Log parameters, eg. CLIENT,CLIENTIP,USER,OPID |
[SessionLogProperties] Section
| Property Name | Supported In | Restrictions | Description |
| Enabled | 0 = log disabled, 1 = log enabled | ||
| Filename | Name of the log file | ||
| Parameters | Log parameters, eg. CLIENT,CLIENTIP,USER,STARTTIME,ENDTIME,OPSFAILED,OPSRECEIVED,AVERAGEOPTIME |
[TraceLogProperties] Section
| Property Name | Supported In | Restrictions | Description |
| Enabled | 0 = log disabled, 1 = log enabled | ||
| Filename | Name of the log file | ||
| Parameters | Log parameters, eg. INFO |
[FontAliases] Section
This section is used to map a font family name to another. The left side is a name that might be specified by the user and the right side is what font to actually use.
[FontAliases] Font name #1 in layer definition = font name #1 on disk Font name #2 in layer definition = font name #2 on disk
[UnmanagedDataMappings] Section
This section is used to map a mapping name to an unmanaged data folder.
[UnmanagedDataMappings] Mapped name in feature source = Data folder on disk
[DBEnvironmentProperties] Section
| Property Name | Supported In | Restrictions | Description |
| LibraryCacheSize | The size for library cache size in MB | ||
| SessionCacheSize | The size for session cache size in MB | ||
| DBPageSize | The size for library DB page in KB | ||
| DBXMLPageSize | The size for library DBXML page in KB | ||
| LibraryLogBufferSize | The size for library log buffer in MB | ||
| SessionLogBufferSize | The size for session log buffer in MB | ||
| DBMaxTransactions | The max number of DB transactions | ||
| SessionDBPageSize | The size for session DB page in KB | ||
| SessionDBXMLPageSize | The size for session DBXML page in KB | ||
| DBTimeout | The time out for lock and transaction in second | ||
| DBMaxLockers | The max number of DB lockers |
Webconfig.ini
Overview
Webconfig.ini controls various aspects of the MapGuide WebExtensions and MapAgent. It is typically located in C:\Program Files\OSGeo\MapGuide\Web\www or /usr/local/mapguideopensource/webserverextensions/www.
[GeneralProperties] Section
| Property Name | Supported In | Restrictions | Description |
| DefaultMessageLocale | if a 5 character locale is specified the first 2 characters must be lower case and the last 2 characters must be upper case. | ISO 639-1 name for the message locale Example: en or en-US | |
| LogsPath | Path where the log files are stored | ||
| ResourcesPath | Path where the localization resource files are stored | ||
| TcpIpMtu | 0 < Value <= 65535 | The TCP/IP maximum transmission unit | |
| FailoverRetryTime | 2.2(+) | Time in seconds for when to retry connecting to a MapGuide server that has gone offline. |
FailoverRetryTime
For a single Web Tier and MapGuide server pair use 1. For a load balanced configuration with multiple MapGuide servers use 60. Values other than 1 will cause a delay when re-establishing a connection with the Web Tier after restarting a MapGuide server.
[AdministrativeConnectionProperties] Section
| Property Name | Supported In | Restrictions | Description |
| MaxConnections | The maximum allowed concurrent connections for this port. | ||
| Port | The port to use for administrative operations. If you change the port # here you must also change the corresponding port # for the server configuration file. |
MaxConnections
The default values in the table below are applicable for a typical user load and a single web tier process space connected to a quad core server. In MapGuide 2.1, the MapGuide server on Windows can only support 62 open connections. Heavy user loads on Windows may create multiple web tier processes and exhaust the available connections with the default settings. MaxConnections may need to be reduced under these circumstances. For MapGuide 2.2 and later, the MapGuide server can support more than 500 connections.
| Connection Type | Platform | Default Value | Tuning Considerations |
| Administrative | MapGuide 2.1 Windows | 2 | Reduce to 1 if server becomes unresposive under heavy load |
| Client | MapGuide 2.1 Windows | 12 | Reduce to 6 if server becomes unresposive under heavy load |
| Site | MapGuide 2.1 Windows | 6 | Reduce to 3 if server becomes unresposive under heavy load |
| Administrative | MapGuide Linux (all versions) MapGuide 2.2 Windows | 2 | Set to 0.5x #of cores on server machine |
| Client | MapGuide Linux (all versions) MapGuide 2.2 Windows | 12 | Set to 3x #of cores on server machine |
| Site | MapGuide Linux (all versions) MapGuide 2.2 Windows | 6 | Set to 1.5x #of cores on server machine |
[ClientConnectionProperties] Section
| Property Name | Supported In | Restrictions | Description |
| MaxConnections | The maximum allowed concurrent connections for this port. | ||
| Port | The port to use for client operations. If you change the port # here you must also change the corresponding port # for the server configuration file. |
[SiteConnectionProperties] Section
| Property Name | Supported In | Restrictions | Description |
| MaxConnections | The maximum allowed concurrent connections for this port. | ||
| Port | The port to use for site operations. If you change the port # here you must also change the corresponding port # for the server configuration file. |
[AgentProperties] Section
| Property Name | Supported In | Restrictions | Description |
| DebugPause | 0 <= Value <= 86400 | Number of seconds the agent pauses before each request, for debugging purpose | |
| DisableAuthoring | 0 = false and 1 = true | Disables Authoring HTTP requests | |
| DisableWfs | 0 = false and 1 = true | Disables OGC Wfs HTTP requests | |
| DisableWms | 0 = false and 1 = true | Disables OGC Wms HTTP requests | |
| ErrorLogEnabled | 0 = false and 1 = true | Enables error logging from the web tier. Must be combined with ErrorLogFilename and GeneralProperties -> LogsPath | |
| ErrorLogFilename | Filename of error log | Name of file to write errors to. Must be combined with ErrorLogEnabled and GeneralProperties -> LogsPath |
[OgcProperties] Section
| Property Name | Supported In | Restrictions | Description |
| WfsPassword | Password to be used for credentials in WFS requests | ||
| WmsPassword | Password to be used for credentials in WMS requests |
[WebApplicationProperties] Section
| Property Name | Supported In | Restrictions | Description |
| TemplateRootFolder | The root folder containing the viewer templates | ||
| WidgetInfoFolder | The folder containing widget info files | ||
| ContainerInfoFolder | The folder containing container info files |
