Serverconfig.ini and Webconfig.ini Documentation and Tuning


Revision History

RevisionDateAuthorComment
0.7August 25, 2011Christine BaoAdd FDOConnectionTimeoutCustom information
0.6August 15, 2011Christine BaoUpdate DB Environment settings
0.5July 7, 2011Bruce DechantUpdated port settings
0.4December 9, 2010Bruce DechantAdded SessionRepositoriesConfig and SessionRepositoriesLimit information
0.3December 6, 2010Bruce DechantAdded PreCacheMaps information
0.2July 2, 2010Trevor WekelAdd some tuning considerations
0.1May 10, 2010Trevor WekelInitial pass at documentation

Table of Contents

  1. Overview
    1. Tuning Quick Links
      1. Serverconfig.ini
      2. Webconfig.ini
    2. Common Validation Information
      1. String Properties
      2. Numeric Properties
  2. Serverconfig.ini
    1. Overview
    2. [GeneralProperties] Section
      1. Locale Parameter
      2. LogsDetail Parameter
    3. [AdministrativeConnectionProperties] Section
      1. MaxConnections
      2. QueueSize
      3. ThreadPoolSize
    4. [ClientConnectionProperties] Section
    5. [SiteConnectionProperties] Section
    6. [HostProperties] Section
    7. [DrawingServiceProperties] Section
    8. [FeatureServiceProperties] Section
      1. CacheSize
      2. DataConnectionPoolExcludedProviders
      3. DataConnectionPoolSize
      4. DataConnectionPoolSizeCustom
      5. FDOConnectionTimeoutCustom
    9. [MappingServiceProperties] Section
    10. [RenderingServiceProperties] Section
    11. [ResourceServiceProperties] Section
      1. RepositoryCheckpointsTimerInterval
    12. [SiteServiceProperties] Section
      1. SessionTimeout
      2. SessionTimerInterval
    13. [TileServiceProperties] Section
    14. [AccessLogProperties] Section
    15. [AdminLogProperties] Section
    16. [AuthenticationLogProperties] Section
    17. [ErrorLogProperties] Section
    18. [SessionLogProperties] Section
    19. [TraceLogProperties] Section
    20. [FontAliases] Section
    21. [UnmanagedDataMappings] Section
    22. [DBEnvironmentProperties] Section
  3. Webconfig.ini
    1. Overview
    2. [GeneralProperties] Section
      1. FailoverRetryTime
    3. [AdministrativeConnectionProperties] Section
      1. MaxConnections
    4. [ClientConnectionProperties] Section
    5. [SiteConnectionProperties] Section
    6. [AgentProperties] Section
    7. [OgcProperties] Section
    8. [WebApplicationProperties] Section

Overview

This document describes the parameters and provides parameter tuning tips for serverconfig.ini and webconfig.ini.

Serverconfig.ini

ParameterDescription
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

ParameterDescription
Failover retry time Tuning failover retry between Server and Web Tier
Web Tier max connectionsTuning 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
Email 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

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