configureWindchill
The running of the configureWindchill target can be broken down into the following steps:
1. Recording initial settings used and backing up the XCONF file that is used
2. Determining system memory and CPUs
3. Calculating memory regions
4. Calculating the optimum server manager and method server configuration
5. Setting additional server manager and method server options
6. Setting Windchill cache property values
7. Setting database property values
8. When running in interactive mode, removing terminal windows, configuring remote access from JMX clients, and garbage collection baiting
Within each of these steps, the assistant executes internal targets to complete specific tasks. The names of these targets are displayed in the output as the assistant executes them.
Defaults for the internal targets are maintained in the <Windchill>/utilities/wca/Configurator.properties file. Since the defaults represent the current best practice values available at the time of the release, PTC may update the values as more relevant data is available. Do not rely on the published content here as it relates to the default values. To verify what the default values are before using the Windchill Configuration Assistant, you can inspect this file.
The sample output shown in the following sections is not intended to provide accurate data about any given system configuration, but shows an example that is relevant to the discussion.
Recording Initial Settings for Windchill Configuration Assistant Run
When the Windchill Configuration Assistant runs, it records initialization information, including the following:
• The Windchill Configuration Assistant and ANT versions (initWCAVersion)
• Java version used by Windchill (initWindchillJavaVersion)
• Windchill version (initWindchillVersion)
Backing Up Exisiting windchillconfigurator.xconf File
Before making any changes, the Windchill Configuration Assistant backs up the existing windchillconfigurator.xconf file as shown in backupXconfFile.
Determining System Memory and CPUs
The first step performed by the Windchill Configuration Assistant when running the configureWindchill target is to determine operating system characteristics, total memory, free memory, and how many CPUs are available in the system.
During the initialization of the assistant, it reports server metrics similar to the following using the init target:
[echo] Number of CPUs detected: 8
[echo] Physical Memory: 12285 MB
[echo] Free Memory: 8473 MB
[echo] Maximum Java heap size=8000 MB
[echo] WT_HOME=D:\PTC\Windchill
[echo] VmVendor=Oracle Corporation
[echo] Operating System=Windows 7
[echo] OS Arch=amd64
[echo] Physical Memory: 12285 MB
[echo] Free Memory: 8473 MB
[echo] Maximum Java heap size=8000 MB
[echo] WT_HOME=D:\PTC\Windchill
[echo] VmVendor=Oracle Corporation
[echo] Operating System=Windows 7
[echo] OS Arch=amd64
Before allocating memory to Windchill, the assistant determines how much memory is available. The server metrics (shown previously) identifies how much total memory is installed on the system and how much memory is free.
To avoid over committing memory to Windchill, the assistant reserves 20% of physical memory for the operating system. The percent allocated to the operating system is governed by property percentPhysicalMemoryReservedForOS. The assistant also discovers the location of the RDBMS and LDAP servers. If either server is configured to run on the same host as Windchill, then the assistant further reduces the amount of free memory available to Windchill.
To assist in determining in the memory allocation, the assistant calls the allocatePhysMem target. The prompts provided when you are running in interactive mode with this target allow you to:
• Specify the percentage of memory to allocate.
• Choose whether to size the overall Windchill memory footprint based on total physical memory or free memory.
• If free memory is selected, then you can enter the amount of free memory (RAM) to override the calculated value
The default values specify that the assistant uses free memory and 80% in its calculation. Therefore, you should stop Windchill before running this step. You should also stop any other applications running on the server that are not expected to be running alongside Windchill.
The percentMemoryRegionReservedForWindchill property governs the percentage of available memory to use for Windchill. The default value is 80. As described earlier, you can change the default value by editing the value in the Configurator.properties file.
In the following example, 8125 MB of memory is reported as free. Based on the 80% default value, the assistant allocates 6500 MB to Windchill:
allocatePhysMem:
[input] Percent of physical memory to reserve for Operating System [20]
[echo] OS memory requirement=2457 MB
[echo] Minimum memory requirement for MethodServer: 768 MB
[echo] Minimum memory requirement for ServerManager: 144 MB
[echo] Windchill Requires a minimum of 912 MB
[echo] Total Memory requirement: 3369.0 MB
[input] Allocate Windchill Memory region from total (12285 MB) or free (8473 MB) physical memory ([free], total)
[echo] Allocating Windchill Memory region from free memory
[input] Enter % of free RAM (8473 MB) to allocate to Windchill: [80]
[echo] % free memory allocated to Windchill: 80
[echo] Windchill Memory Region= 6778 MB
[input] Percent of physical memory to reserve for Operating System [20]
[echo] OS memory requirement=2457 MB
[echo] Minimum memory requirement for MethodServer: 768 MB
[echo] Minimum memory requirement for ServerManager: 144 MB
[echo] Windchill Requires a minimum of 912 MB
[echo] Total Memory requirement: 3369.0 MB
[input] Allocate Windchill Memory region from total (12285 MB) or free (8473 MB) physical memory ([free], total)
[echo] Allocating Windchill Memory region from free memory
[input] Enter % of free RAM (8473 MB) to allocate to Windchill: [80]
[echo] % free memory allocated to Windchill: 80
[echo] Windchill Memory Region= 6778 MB
Calculating Memory Regions
In this next step, the assistant partitions the allocated memory into two regions. These regions are for the method servers and the server manager. The assistant uses percentages to calculate the size of the two memory regions. The default allocations are as follows:
• Server manager: 10%
• Method servers: 90%
You can change the server manager allocation percentage by editing the Configurator.properties file or by entering a new value when you are running the Windchill Configuration Assistant in interactive mode. The remaining memory is used for the method servers.
The following example accepts the defaults and shows the resulting memory allocations:
[input] Enter % of Windchill Memory (6778) to allocate to ServerManager Heap: [10]
[echo] % Windchill memory to allocate to ServerManager: 10
[echo] ServerManager memory region..... 677 MB
[echo] MethodServer memory region..... 6100 MB
[echo] % Windchill memory to allocate to ServerManager: 10
[echo] ServerManager memory region..... 677 MB
[echo] MethodServer memory region..... 6100 MB
Calculating Optimum Server Manager and Method Server Configuration
After the memory region sizes have been calculated, the assistant determines the number of method servers to configure. It does this by considering both the size of the method server memory region and the number of CPUs.
The configureMethodServerService target calculates the number of method servers and background method servers based on the number of CPUs reported by the operating system. It then uses a lookup table containing the ratio of CPU to method servers that is defined in Configurator.properties to determine the ideal number of method servers for the number of CPUs. A second lookup table is used to determine the optimum number of method servers based on operating system and method server memory region size. If more than one method server is recommended and you are not running in interactive mode, then one of the method servers is configured as a background method server. All other method servers are configured as foreground method servers. When you are running in interactive mode and the assistant finds sufficient resources to run multiple method servers, it may prompt you to configure a background method server. If you do not want a background method server configured, enter n when prompted.
If the assistant determines that the current Windchill installation belongs to a cluster, then it will only offer to configure a background method server on the host configured as the cluster master.
If you want to configure more than one background method server, you must manually configure the additional background method servers. For details on configuring multiple background method servers, see Configuring Background Method Servers.
In the following example, the assistant recommends 3 method servers for the 8 CPU server and offers to configure a background method server:
configureMethodServerService:
[echo] Recommended number of MethodServers for 8 CPUs = 3
[echo] set outputProperty to default =3
[echo] Recommended number of MethodServers for 6100MB on Windows 7 (64bit) is 3
[echo] Recommended number of MethodServers based on available resources=3
[input] Enter number of MethodServers to configure (current=1): [3]
[input] Enter MethodServer max heap size (MB): [2033]
[echo] Setting max heap size for MethodServer to 2033
[input] Enter MethodServer initial heap size (MB): [2033]
[echo] Setting initial heap size for MethodServer to 2033
[input] Do you want to configure a BackgroundMethodServer (y/n)? ([y], n)
[echo] Configuring Background MethodServer
[echo] Recommended number of MethodServers for 8 CPUs = 3
[echo] set outputProperty to default =3
[echo] Recommended number of MethodServers for 6100MB on Windows 7 (64bit) is 3
[echo] Recommended number of MethodServers based on available resources=3
[input] Enter number of MethodServers to configure (current=1): [3]
[input] Enter MethodServer max heap size (MB): [2033]
[echo] Setting max heap size for MethodServer to 2033
[input] Enter MethodServer initial heap size (MB): [2033]
[echo] Setting initial heap size for MethodServer to 2033
[input] Do you want to configure a BackgroundMethodServer (y/n)? ([y], n)
[echo] Configuring Background MethodServer
When the assistant configures a background method server it appoints one of the foreground method servers as the background method server and reduces the number of foreground method servers by one. Memory for method servers (including the background method server - if any) is allotted from the method server memory region.
All method servers (including background method server) are assigned identical Java heap sizes. The heap size is calculated by simply dividing the method server heap region by the sum of background plus foreground method servers. The calculated heap size must not exceed the heap size limit defined for the operating system and memory model (for example, 32bit or 64 bit). In the example above, both the background and foreground method servers were assigned heaps of 2033 MB.
Next, the heap size for the server manager is set. Interactively, you can use the default presented (which is the server manager memory region calculated under allocatePhysMem) or enter your own value. The following example shows the use of the default value:
configureServerManager:
[input] Enter ServerManager max heap size (MB): [812]
[echo] Setting max heap size for ServerManager to 812
[input] Enter ServerManager initial heap size (MB): [812]
[echo] Setting initial heap size for ServerManager to 812
[input] Enter ServerManager max heap size (MB): [812]
[echo] Setting max heap size for ServerManager to 812
[input] Enter ServerManager initial heap size (MB): [812]
[echo] Setting initial heap size for ServerManager to 812
After the number of method servers and the heap sizes for both the method servers and server manager have been set, the assistant configures additional Java command line options. These command line options fine tune the heap generation sizes for maximum garbage collection throughput, including the number of parallel threads.
The Java collector used with Windchill uses multiple CPUs to reduce the pause time of full garbage collections. Windchill uses multiple JVMs on a single system. The assistant allows you to tune the garbage collection by specifying the number of parallel threads that can be used for garbage collection on both the method servers and the server manager. The assistant determines the default values, and displays them when the assistant is run. In the following example, the assistant recommends two threads for each method server:
[echo] Calculated ParallelGCThreads=2
[input] Enter MethodServer parallel GC threads: [2]
[input] Enter MethodServer parallel GC threads: [2]
In the following example, the assistant recommends two threads for the server manager:
[echo] Calculated ParallelGCThreads=2
[input] Enter ServerManager parallel GC threads: [2]
[input] Enter ServerManager parallel GC threads: [2]
Setting Windchill Cache Property Values
The assistant sets cache settings in Windchill application properties. The first set of properties it considers are those that size in-memory data caches.
Optimal cache tuning is difficult unless the system is under load. The Windchill Configuration Assistant simply suggests initial cache sizes based on the number of rows it finds in specific tables in the database.
The following Windchill cache properties are configured:
wt.admin.cache.maxDomains
wt.cache.size.AclCache
wt.cache.size.EnumerationDefinitionCache
wt.cache.size.IBADefViewManager$IBADefViewCache
wt.cache.size.IndexListCache
wt.cache.size.PagingSessionCache
wt.cache.size.PolicyAcl
wt.cache.size.PreferenceCache
wt.cache.size.RoleAccessCache
wt.cache.size.SessionCache
wt.cache.size.StandardFederatedServerHelper$RemoteObjectIdCache
wt.cache.size.StandardFvService$ActiveFolderCache
wt.cache.size.StandardUfidSrvService$RemoteObjectIdCache
wt.cache.size.StructEnumAttTemplateCache
wt.cache.size.TypeDefinitionCache2
wt.cache.size.WTPrincipalCache
wt.services/rsc/default/ObjectReferenceCacheTable/ContainerCache.Size
wt.services/src/default/ObjectReferenceCacheTable/ContainerTeamCache
Each cache comprises multiple entries, where each entry effectively represents one row in the corresponding database table. Windchill caches should be sized to maintain only recently accessed data rows (also known as the “working set”).
The assistant uses two basic algorithms to calculate cache sizes. The first cache sizing algorithm obtains the total number of rows in a database table and sizes the cache based on a configurable percentage of the table row count total.
The configurable percentages are defined using the following properties in Configurator.properties:
WTContainer.cache.percent
ContainerTeam.cache.percent
WTPrincipal.cache.percent
PolicyAcl.cache.percent
RemoteObjectInfo.cache.percent
AdministrativeDomain.cache.percent
Session.cache.percent
RoleAccess.cache.percent
Preference.cache.percent
PagingSession.cache.percent
IBADefinition.cache.percent
EnumerationDefinitionCache.cache.percent
LWCStructEnumAttTemplate.cache.percent
LWCTypeDefinition.cache.percent
FvVault.cache.percent
IndexPolicyList.cache.percent
The second cache sizing algorithm sizes caches based on the number of users defined in the system and the percentage of those users that are expected to be concurrently executing Windchill requests during peak workloads. The predicted percentage of all users that will be concurrently active is governed by property peakActiveUsersPercent and the default value is 10.
Regardless of which algorithm is executed, the resulting cache size is the larger of the out-of-the-box size and the calculated cache size. A configurable size limit is applied to each cache in case the sizing algorithm over allocates memory. The maximum size for all of the above caches is governed by properties <CacheName>.cache.size.limit that are defined in Configurator.properties. You can override the calculated values when running the assistant interactively For example, the following lines show the lines that set the session cache property:
[echo] Named users: 100
[input] Estimated peak number of active users: [10]
[echo] Expected peak active users: 10
[echo] Configuring wt.cache.size.SessionCache currentSize=500 rowcount=100 percent=20
[input] Set Session Cache Size (max=2000): [500]
[input] Estimated peak number of active users: [10]
[echo] Expected peak active users: 10
[echo] Configuring wt.cache.size.SessionCache currentSize=500 rowcount=100 percent=20
[input] Set Session Cache Size (max=2000): [500]
After sizing the data caches, the assistant then considers various properties that configure database connections, JDBC statement cache sizes, and so on. These properties all reside in <Windchill>/utilities/wca/Windchill/db/db.properties. Many of these properties have initial sizes that are suited for environments with minimal resources such as laptop or small desktop systems. When configuring Windchill on servers with larger heaps these properties should be adjusted accordingly.
If you want to calculate the WTPrincipalCache size manually, see this topic
Setting Database Property Values
The assistant increases the following database property values based on the method server heap sizes. The table below shows estimated property values based on difference heap sizes (recommended values may change; see the Configurator.properties file for the latest set of values that are used):
|
Property Name
|
<1000 MB
|
1000 - 1999 MB
|
>=2000 MB
|
Default
|
|---|---|---|---|---|
|
wt.pom.maxDbConnections
|
10
|
15
|
15
|
10
|
|
wt.pom.minDbConnections
|
5
|
5
|
5
|
5
|
|
wt.pom.refreshCache.size
|
100
|
200
|
300
|
100
|
|
wt.pom.rowPrefetchCount
|
20
|
20
|
20
|
20
|
|
wt.pom.statementCacheSize
|
50
|
50
|
50
|
50
|
Other database related properties that are considered by the assistant are not constrained by memory or CPU resources. These properties are shown in the following table:
|
Property Name
|
<1000 MB
|
1000 - 1999 MB
|
>=2000 MB
|
Default
|
|---|---|---|---|---|
|
wt.pom.inClauseBindOptimizationCardinality
|
-1
|
-1
|
-1
|
-1
|
|
wt.pom.inClauseUseBindOptimization
|
true
|
true
|
true
|
true
|
|
wt.pom.oracle.disableAlwaysSemiJoin
|
false
|
false
|
false
|
false
|
Interactive Mode Configuration Options
When you run the configureWindchill target in interactive mode, you have addition configuration options as described in the following sections.
Removing the Terminal Windows
After configuring database properties, there is a check for removing terminal windows. The following prompt displays:
[input] Do you want to remove the xterm/cmd terminal windows (y/n)? (y, [n])
The default is not to remove them. Enter y to have the assistant remove them.
Configuring Remote Access from JMX Clients
The Windchill Configuration Assistant prompts you to configure the server manager to allow remote access from JMX clients, such as JConsole. Such clients can be used to interact with the Windchill MBeans to manage and monitor the application. However, to connect using a JMX client from a remote workstation, you must configure additional Windchill properties.
Two modes of access are supported:
• Authenticated
When configuring authenticated remote access, the assistant creates two users named monitorRole and controlRole and assigns each a password. Both of these users must have an entry in the JDK jmxremote.access file found at <JRE>/lib/management/jmxremote.access:
◦ The monitorRole provides read-only access.
◦ The controlRole is granted read-write access.
Remote users must supply one of the two role names and the associated password to gain access to Windchill MBeans. The user names and passwords for the two roles are written to a file named <Windchill>/Windchill/jmxremote.password and that file is referenced by properties on the server manager java command line.
• Anonymous
When anonymous remote access is enabled, any remote client can connect without supplying a user name or password.
 |
Anonymous users are granted unrestricted access.
|
The following example shows the prompts that are displayed to set up authenticated remote access:
[input] Do you want to enable authenticated (non SSL) remote JMX access to the ServerManager(y/n)? (y, [n])
y
[echo] Configuring authenticated remote JMX access
[input] servermanager monitor role name: [monitorRole]
[input] servermanager monitor role password: [bigBrother15]
[input] servermanager control role name: [controlRole]
[input] servermanager control role password: [autoCrat100]
y
[echo] Configuring authenticated remote JMX access
[input] servermanager monitor role name: [monitorRole]
[input] servermanager monitor role password: [bigBrother15]
[input] servermanager control role name: [controlRole]
[input] servermanager control role password: [autoCrat100]
Configuring Garbage Collection Baiting (GCBaiter)
To reduce the likelihood of method server heap exhaustion due to an unbounded memory operation, the assistant configures a feature known as Garbage Collection Baiting (GCBaiter). When the method server heap is 100% utilized, the JVM will generally crash with an OutOfMemoryError. The GCBaiter attempts to identify the user operation that is consuming most of the available heap prior to the OutOfMemoryError and then terminates it. The GCBaiter is initiated automatically by the JVM when it detects a low memory condition (for example, when the JVM Garbage Collector needs to collect SoftReferences). The GCBaiter uses the MethodServer.gcBaiting.suggestedMinAvailableHeapPercent property to detect when the method server available heap space has fallen below the minimum requirement.
The Windchill Configuration Assistant calculates the minimum available heap value used by GCBaiter as a percentage of the maximum method server heap size. The default value is 5% and is governed by property MethodServer.gcBaiting.suggestedMinAvailableHeapPercent. Note that the assistant does not set the DisableExplicitGC Java command line option when GCBaiting is enabled.
The following example shows the prompts that are displayed to set up Garbage Collection Baiting target configureGCBaiter:
configureGCBaiter:
[input] Do you want to enable automatic termination of requests to avoid OutOfMemory (y/n)? ([y], n)
[input] Minimum percentage of heap available: [5]
[xslt] Processing <Windchill>\codebase\WEB-INF\methodServerMBeanConfig.xml to <Windchill>\utilities\wca\conf\windchillmethodServerMBeanConfig.xml
[xslt] Loading stylesheet <Windchill>\utilities\wca\GCBaiter.xsl
[xslt] Add minAvailableHeapThreshold: 5
[input] Do you want to enable automatic termination of requests to avoid OutOfMemory (y/n)? ([y], n)
[input] Minimum percentage of heap available: [5]
[xslt] Processing <Windchill>\codebase\WEB-INF\methodServerMBeanConfig.xml to <Windchill>\utilities\wca\conf\windchillmethodServerMBeanConfig.xml
[xslt] Loading stylesheet <Windchill>\utilities\wca\GCBaiter.xsl
[xslt] Add minAvailableHeapThreshold: 5