Service configuration files

The properties of service configurations are maintained in a file for each configuration in the GIS server's cfg directory. When you add a new service configuration to the GIS server, a new configuration file is automatically created. When a configuration is deleted, its configuration file is deleted from the cfg directory.

The name of a service configuration file follows the pattern <configuration name>.<service type>.cfg. For example, the map service Redlands would have the name Redlands.MapServer.cfg.

It's possible to add a configuration to the GIS server by manually creating a configuration file in the cfg directory, and it's possible to delete a configuration by deleting its file from the cfg directory. In both cases, the new or deleted configuration will not be recognized by the server until the server object manager (SOM) is restarted. If the SOM encounters a corrupted configuration file, the SOM will log a warning and ignore the configuration.

Caution:

You must stop the ArcGIS Server Object Manager service before making manual changes to a service configuration file.

Service configuration tags

The following are the tags, their meanings, and example values in a service configuration file:

<Description>

An optional string that is the description of the service configuration.

<Properties>

The list of properties of the service configuration. The subtags are properties specific to the service configuration type.

The following table lists which <Properties> subtags each type of service supports (GeometryServer supports no subtags). The table is followed by a description of each tag in alphabetical order.

GeocodeServer	GeodataServer	GlobeServer	GPServer	ImageServer	MapServer	FeatureServer
Locator	FilePath	FilePath	MapFile	Path	FilePath	EnableZDefaults
LocatorWorkspacePath	OutputDir	MaxRecordCount	DataFrame	ServiceDefinition	FileName	ZDefaultValue
LocatorWorkspaceConnectionString	VirtualOutputDir	MaxBufferCount	Toolbox	OutputDir	OutputDir	xssPreventionEnabled
SuggestedBatchSize	MaxRecordCount	CacheDir	JobsDirectory	VirtualOutputDir	VirtualOutputDir	xssPreventionRule
MaxBatchSize	ConnectionCheckInterval	SOMCacheDir	JobsVirtualDirectory	ServiceURL	SupportedImageReturnTypes	xssInputRule
MaxResultSize		ClientCachingAllowed	ExecutionType		MaxImageHeight	xssTrustedFields
ConnectionCheckInterval		ConnectionCheckInterval	OutputDir		MaxRecordCount
			VirtualOutputDir		MaxBufferCount
			MaximumRecords		MaxImageWidth
			LocalJobsDir		IsCached
			ShowMessages		CacheOnDemand
					IgnoreCache
					ClientCachingAllowed
					CacheDir
					SOMCacheDir
					ConnectionCheckInterval
					SchemaLockingEnabled
					UseLocalCacheDir
					MaxDomainCodeCount

<CacheDir>

MapServer, GlobeServer

A string that represents the path to a location on the file system where the map or globe cache is stored. For globe services, the path should always end with \GlobeCache for Windows or /GlobeCache for Linux/Solaris.

<CacheOnDemand>

MapServer

A Boolean tag specifying whether cache tiles should be created on demand and added to the server cache directory as users navigate the map. A value of true means that tiles will be added on demand. The default value is false.

Learn more about on-demand caching

<ClientCachingAllowed>

MapServer, GlobeServer

A Boolean tag specifying whether client applications can locally cache tiles from this service. The default is true. Set this value to false if you anticipate that your cache will be updated often and you don't want clients to have to clear their cache to see the updates.

<ConnectionCheckInterval>

GeocodeServer, GeodataServer, GlobeServer, MapServer

An integer representing the number of seconds between validity checks (and, if necessary, repairs) on ArcSDE data connections that contribute to a service. By default, this property is not included in the .cfg file, and the interval is 300 seconds. You can add this tag to the .cfg file to modify the interval.

Although the default is usually sufficient, a lower value such as 60 or 120 may be appropriate if your workspace is acting unreliable or unstable. Avoid extremely low values, since frequent checks can slow performance.

To disable the connection checks, specify a value of 0.

A client must make a request to the service instance in order to trigger the check, even once the ConnectionCheckInterval has elapsed. For this reason, ConnectionCheckInterval cannot validate data connections on idle services. To check idle services, use ServiceKeepAliveInterval.

<DataFrame>

GPServer

A string representing the name of the data frame containing the tool layer associated with the geoprocessing service. This tag is not used when the geoprocessing service is associated with a toolbox only.

<EnableZDefaults>

FeatureServer

A Boolean tag specifying whether default Z values are enabled for the service. The default is false. To enable default Z values, set this property to true.

<ExecutionType>

GPServer

A string that denotes whether geoprocessing jobs will be run in a Synchronous or Asynchronous manner.

<FileName>

MapServer

A string representing the name of the map service definition (MSD) file contributing to the service. This tag is only used when the map service was published in ArcMap using the Map Service Publishing toolbar. It contains only the name of the MSD file, and assumes that the MSD is located in the server input directory (c:\arcgisserver\arcgisinput by default).

<FilePath>

MapServer, GeodataServer, GlobeServer

A string representing a path to the document that the service configuration will serve. For GeodataServer, this is the path to the .sde file containing the .sde connection information, or it can represent a path to a personal geodatabase.

<IgnoreCache>

MapServer

A Boolean tag specifying whether the cache should be used. A value of true means that the map will be rendered dynamically instead of using the cache. You might use this setting if you had previously created the cache but changed the map and want users to immediately see the edits. This also gives you a chance to see how the service looks before updating or re-creating your cache.

You will see slower performance when you set this tag to true because the server must draw the map on each request.

<IsCached>

MapServer

A Boolean tag specifying whether this service has a cache of prerendered tiles on disk. The service is considered cached if a tiling scheme and cache directory have been defined. Services do not have a cache until you create one, so by default, this tag is false.

<JobsDirectory>

GPServer

A string representing the path to the server jobs directory associated with the service. Jobs directories are used by geoprocessing services for writing scratch and output data.

<JobsVirtualDirectory>

GPServer

A string that represents the URL of the virtual directory that points to the physical location specified in the <JobsDirectory> tag.

<LocalJobsDir>

GPServer

A Boolean property that specifies whether geoprocessing services will write scratch workspaces to the local system TEMP directory on the server object container (SOC) while jobs are processing. By default, this tag is not visible, and the value is set to false.

Geoprocessing services execute faster when the scratch workspace is at a local path. In distributed installations of ArcGIS Server, namely those that use multiple SOC machines, you can improve performance by allowing the SOC account Read and Write permissions to your system TEMP directory and choosing to use the local jobs directory.

After execution, the scratch workspace is copied from the TEMP directory to the JobsDirectory, where it is accessible by all clients.

<Locator>

GeocodeServer

A string that represents the name of the address locator for a GeocodeServer.

<LocatorWorkspaceConnectionString>

GeocodeServer

A string that contains parameters for a connection to a locator stored in a geodatabase.

<LocatorWorkspacePath>

GeocodeServer

A required string for file-based locators that represents the path to the location on disk where the locator file is stored.

<MapFile>

GPServer

A string representing the path to the map document containing the tool layers associated with the geoprocessing service. This tag is not used when the geoprocessing service is associated with a toolbox only.

<MaxBatchSize>

GeocodeServer

An integer that represents the maximum number of result records returned by the FindAddressCandidates method on a GeocodeServer.

<MaxBufferCount>

MapServer, GlobeServer

An integer that represents the maximum number of features that can be buffered by the service at draw time per layer.

<MaxDomainCodeCount>

MapServer

An integer that represents the maximum number of domain codes that can be returned from all fields, subtypes, layers, and tables in a map service. By default, this property is not included in the .cfg file and the default value is 25,000. You can add this tag to the .cfg file to modify the value.

In a large multi-user map service, such as an online enterprise resource planning (ERP) system, the number of domain codes returned by the <MaxDomainCodeCount> property may exceed the default value. If this occurs, the service will continue to run normally, but MapServer will drop all domains to maintain server performance. Additionally, an error documenting the event will be recorded in the server activity log. If you require MapServer to return a greater number of domain codes in the map service than the default value, add the <MaxDomainCodeCount> property to the .cfg file and specify the desired default value. Please note that the performance of the map service may be affected when MapServer is required to return more than 25,000 domain codes.

<MaxImageHeight>

MapServer

An integer representing the maximum height (in pixels) of images the map service will export. The default is 2048.

<MaxImageWidth>

MapServer

An integer representing the maximum width (in pixels) of images the map service will export. The default is 2048.

<MaximumRecords>

GPServer

An integer representing the maximum number of records that will be returned by a geoprocessing job.

<MaxRecordCount>

MapServer, GeodataServer, GlobeServer

An integer that represents the maximum number of result records that can be returned by query, find, and identify operations on a map or globe service or by the TableSearch method on a geodata service.

<MaxResultSize>

GeocodeServer

An integer that represents the maximum number of result records returned by the FindAddressCandidates method on a GeocodeServer.

<OutputDir>

MapServer, GeodataServer, GPServer, ImageServer

A string that represents the path to a location on the file system to which the service will write its output. When you create a new service configuration, this property is copied from the server output directory path that you specified. If you want the service's output to be cleaned by the GIS server, this path should be a path to a server output directory.

<Path>

ImageServer

A string representing the path to the data that the service configuration will serve.

<SchemaLockingEnabled>

MapServer

A Boolean tag that determines whether the map service will acquire schema locks for map layers that come from a geodatabase. By default, the locks are acquired, so this property is true. If the locks impede your workflow, you can add this tag and set it to false to disable schema locking.

Use caution when disabling schema locking. When the schema locks are not acquired, other users have the ability to alter the schema of the dataset, which could have unexpected effects for those who use the map service. You should only disable schema locking if your workflow explicitly requires it.

The <SchemaLockingEnabled> tag is not included in the service configuration file by default. You must explicitly add it and set it to false if you want to disable schema locking.

<ShowMessages>

GPServer

Boolean tag indicating whether the service will return error, warning, and informational messages from the geoprocessing operation. Messages are helpful for development and debugging, but they may contain path names and other sensitive information that you don't want to reveal in public-facing services. The default is false.

<ServiceDefinition>

ImageServer

A string that represents the path to the source image service definition file for an image service. This tag is only included when you publish from an image service definition file (.ISCDef).

<ServiceURL>

ImageServer

A string representing the URL of the service on Image Server (refers only to image services published from an image service definition file [.ISCdef]).

<SOMCacheDir>

MapServer, GlobeServer

A string representing the path to the server cache directory used by the service. Note that this tag only contains the path of the cache directory; the full path to the cache is specified in the <CacheDir> tag.

<SuggestedBatchSize>

GeocodeServer

An integer that represents the number of records that will be located at a time for batch geocoding.

<SupportedImageReturnTypes>

MapServer

Possible values are MIME or URL. Specifies whether images will be returned as MIME data or written to disk (MIME + URL). If you choose URL, you must have a server output directory specified for the configuration.

<Toolbox>

GPServer

A string representing the path to the toolbox associated with the geoprocessing service. This tag is not used when the geoprocessing service is associated with a tool layer in a map document. In that event, the <MapFile> and <DataFrame> tags would be used.

<UseLocalCacheDir>

A boolean defining whether the ArcGIS Server map caching mechanism will write bundle files to a local directory and copy them into a shared cache directory, instead of writing the files directly into the shared cache directory. This option can improve performance, but it only applies to the compact cache storage format when multiple machines are working on the cache. The default is false. See Local cache directories on the server for more information on the local cache directory location and requirements.

<VirtualGlobeCacheDir>

GlobeServer

A string that represents the URL of the virtual directory that points to the physical location specified in the <GlobeCacheDir> tag. For globe services only.

<VirtualOutputDir>

MapServer, GeodataServer, GPServer, ImageServer

A string that represents the URL of the virtual directory that points to the physical location specified in the <OutputDir> tag. When you create a new service configuration, this property is copied from the server output directory's URL that you specify.

The following is an example of the <Properties> tag and its subtags for a MapServer configuration:

<Properties>
	<FilePath>/cup1/arcgis/java/samples/data/ServerData/Yellowstone/Yellowstone.mxd</FilePath>
	<MaxRecordCount>1000</MaxRecordCount>
	<MaxBufferCount>100</MaxBufferCount>
	<MaxImageWidth>2048</MaxImageWidth>
	<MaxImageHeight>2048</MaxImageHeight>
	<SupportedImageReturnTypes>URL</SupportedImageReturnTypes>
	<MaxDomainCodeCount>25000</MaxDomainCodeCount>
	<OutputDir>/cup1/arcgis/server/serverdir/arcgisoutput</OutputDir>
	<VirtualOutputDir>http://cup:8399/arcgis/server/arcgisoutput</VirtualOutputDir>
</Properties>

The following is an example of the <Properties> tag and some of its subtags for a GeocodeServer configuration whose locator is an ArcSDE locator:

<Properties>
	<Locator>GDB.Portland</Locator>
		<LocatorWorkspaceConnectionString>
		ENCRYPTED_PASSWORD=0002c06e3bc49d6412c06c1baa554d00;
		SERVER=doug;
		INSTANCE=5151;
		USER=gdb;
		VERSION=SDE.DEFAULT
	</LocatorWorkspaceConnectionString>
	<SuggestedBatchSize>1000</SuggestedBatchSize>
	<MaxResultSize>500</MaxResultSize>
	<MaxBatchSize>1000</MaxBatchSize>
</Properties>

<Extension>

The <Extension> tag appears for each type of server object extension, or capability, that the configuration supports. This tag contains subtags that further describe the extension.

<TypeName>

The name of the type of server object extension, or capability. For example: WMSServer.

<Enabled>

A Boolean property that specifies whether the extension is enabled (true) for that configuration or disabled (false).

<Properties>

Some server object extensions may have unique properties that are detailed here in subtags.

<Info>

Some server object extensions can have Web access, which is determined by the <WebEnabled> and <WebCapabilities> tags inside a parent <Info> tag. The <Info> tag can appear beneath both the <ServerObjectConfiguration> and <Extension> tags.

<Recycling>

The list of recycling properties of the service configuration. This tag contains subtags <Start> and <Interval>.

Note:

If the <Recycling> tag is missing or any of its subtags are invalid, recycling will be switched off for the configuration.

<StartTime>

A required string that represents the recycling start time, which is the first time at which recycling will occur for the service configuration. The time specified is in 24-hour notation. For example, to set the start time at 2:00 p.m., the StartTime property would be 14:00. The default is 00:00, meaning that recycling will happen for the first time at midnight.

<Interval>

A required integer that defines the time between recycling operations in seconds. For example, to recycle the configuration every hour, this property would be set to 3600. The default value is 86400, meaning recycling will happen once every 24 hours.

The following is an example of the <Recycling> tag and its subtags:

<Recycling>
	<StartTime>00:00</StartTime>
	<Interval>36000</Interval>
</Recycling>

<Info>

This tag contains the <WebEnabled> and <WebCapabilities> subtags that describe the level of Web access for a service. This tag can appear beneath both the <ServerObjectConfiguration> and <Extension> tags.

<WebEnabled>

A Boolean property that describes whether clients will be able to access the service through HTTP. The default is true.

Note:

This tag must have <Info> as a parent tag.

<WebCapabilities>

A comma-delimited string that contains the allowed operations for the service. Allowed operations describe what a client can do with a service. Specifically, they refer to the groups of methods from the service's Web Service Description Language (WSDL) that clients will be able to call. For a list of operations by service type, see "Limiting what users can do with a service" in the topic Tuning and configuring services.

Note:

This tag must have <Info> as a parent tag.

<IsPooled>

A required string indicating whether the services created by this configuration are pooled (true) or not pooled (false).

<IsRunning>

Boolean tag indicating whether the service is running (true) or stopped (false).

<MinInstances>

An integer specifying the minimum number of instances for the service's pool. The default is 0.

<MaxInstances>

An integer specifying the maximum number of service instances that can be running at any time. The default is 0.

<WaitTimeout>

An optional integer specifying the maximum amount of time in seconds allowed between a client's requesting a service and getting a service. The default is 60.

<IdleTimeout>

Time in seconds that a service instance is allowed to be idle before the instance is destroyed. This setting allows your service to return to the minimum number of instances after a period of time if none of the instances are in use. The default value is 1800.

<UsageTimeout>

An optional integer specifying the maximum amount of time in seconds a client can hold on to a service before it is automatically released. The default is 600.

<CleanupTimeout>

Time in seconds that a service instance should wait after a shutdown command for the purpose of allowing cleanup operations to finish. The default is 30.

<StartupTimeout>

Maximum time in seconds that the service startup can take before startup is considered a failure. The default is 300.

<Isolation>

A required string indicating whether the configuration's service has high isolation (high) or low isolation (low).

<StartupType>

An optional string that specifies whether the configuration is started by the SOM when the SOM starts, or if it needs to be manually started by an administrator. The valid values are automatic or manual. The default is automatic.

<InstancesPerContainer>

An integer representing how many instances of a service are allowed to run within one container process (ArcSOC.exe). When running in high isolation (see <Isolation>), this value defaults to 1 and should not be changed. When running in low isolation, this value defaults to 8 and can be set to any integer between 1 and 256.

<ServiceKeepAliveInterval>

An integer representing the number of seconds between validity checks (and, if necessary, repairs) on ArcSDE data connections that contribute to an idle service instance. Checks begin on the idle service once it has been idle for one interval. Checks continue at the interval until the service is used again.

By default, the ServiceKeepAliveInterval is set to -1, meaning that checks are not performed. If you find that your services are initially unavailable after some period of sitting idle, but then recover on subsequent accesses, try setting this property to a value such as 1800 (in other words, 30 minutes). You can adjust this value to a shorter interval if you still frequently discover unresponsive services.

Setting ServiceKeepAliveInterval may also help you if firewalls are closing ports to ArcSDE after your services sit idle for a certain period of time. In this situation your choice of ServiceKeepAliveInterval may be influenced by firewall timeout settings.

The difference between ServiceKeepAliveInterval and ConnectionCheckInterval is that ServiceKeepAliveInterval applies to idle service instances, whereas ConnectionCheckInterval applies to service instances in frequent use.

<xssPreventionEnabled>

FeatureServer

A Boolean property that specifies whether XSS (Cross Site Scripting) prevention is enabled for the service. The default is true. To disable XSS prevention, set the property to false.

<xssPreventionRule>

FeatureServer

A string that specifies the prevention rule when XSS (Cross Site Scripting) prevention is enabled. The default is input, which means that attribute edits containing potentially harmful content are blocked. Additionally, if you want to encode query results containing potentially harmful content, specify this property as inputOutput.

<xssInputRule>

FeatureServer

A string that specifies the input rule when XSS (Cross Site Scripting) prevention is enabled. The default is rejectInvalid, which means that attribute edits containing potentially harmful content are rejected. Conversely, if you want to encode potentially harmful attribute edits instead of rejecting them, specify this property as sanitizeInvalid.

<xssTrustedFields>

FeatureServer

A string that allows you to specify fields in a feature layer that can be excluded from the XSS (Cross Site Scripting) prevention settings. The fields that are excluded are "trusted" and any attribute edits are allowed to bypass the XSS prevention rules. By default, there are no trusted fields.

To specify trusted fields, use the following syntax:

{"LayerA": "FieldA,FieldB", "LayerB": "FieldA"}

You can also use a wildcard (*) to set all of the fields in a layer to be trusted. For example:

{"LayerC": "*"}

If no fields are specified for a layer, none of the fields in the layer will be trusted.

<ZDefaultValue>

FeatureServer

An integer representing the default Z value for the service. The default is 0.