Client properties file

Sample client properties file

You can use the sampleClient.properties file that is in the wxs_home/properties directory to create your properties file.

You can use the Client.Net.properties file that is in the net_client_home\config\ directory to create your properties file.

Specifying a client properties file for Java™ clients

You can specify the client properties file in one of the following ways. Specifying a setting by using one of the items later in the list overrides the previous setting. For example, if you specify a system property value for the client properties file, the properties in that file override the values in the objectGridClient.properties file that is in the class path.

1. As a well-named file anywhere in the WebSphere Application Server class path. Putting this file in the system current directory is not supported:

   objectGridClient.properties

2. As a system property in either a stand-alone or WebSphere Application Server configuration. This value can specify a file in the system current directory, but not a file in the class path:

   -Dobjectgrid.client.props=file_name

   Note: In a WebSphere Application Server configuration, the client properties file must be in the classpath if you want to specify a particular client properties file to use with the system property; for example, was_root/properties or profile_root/properties, depending on whether you want the properties file to apply to a specific profile, or the entire installation.
3. As a programmatic override using the ClientClusterContext.getClientProperties method. The data in the object is populated with the data from the properties files. You cannot configure security properties with this method.

Specifying a client properties file for WebSphere eXtreme Scale Client for .NET

The default client properties file is in the net_client_home\config\Client.Net.properties directory. If you want to specify your own property files, supply the full property file path to each Connect method call.

IGridManager gm = GridManagerFactory.GetGridManager( );
ICatalogDomainInfo cdi = gm.CatalogDomainManager.CreateCatalogDomainInfo( "localhost:2809" );
ccc = gm.Connect( cdi, @"C:\MyLocation\MyClient.properties" );
grid = gm.GetGrid( ccc, gridName );

Client properties

Client properties

enableDynamicConfiguration

When set to true, any changes that are made to the requestRetryTimeout property in the client properties file are detected dynamically. The new property value is used immediately to calculate the new request retry timeout value.

Default: false

Valid values: true, false

listenerHost

Specifies the host name to which the Object Request Broker (ORB) or eXtremeIO (XIO) transport protocol binds for communication. If your configuration involves multiple network cards, set the listener host and port to let the transport mechanism in the JVM know the IP address for which to bind. If you do not specify which IP address to use, symptoms such as connection timeouts, unusual API failures, and clients that seem to hang can occur.

Default: localhost

Valid values: port number

listenerPort

Specifies the port number to which the Object Request Broker or the eXtremeIO (XIO) transport protocol binds for communication. The port number that is defined for listenerPort is used for communication between a client and a catalog server, and communication between a container server and a catalog server that are in the same domain. It is also used for interdomain and intradomain communication between catalog servers.

Note: When a data grid server is run inside WebSphere Application Server and the ORB transport protocol is being used, another port ORB_LISTENER_ADDRESS must also be opened. The BOOTSTRAP_ADDRESS port forwards requests to this port. If you are using the XIO transport protocol, the XIO_ADDRESS port must be opened.

Default: 2809

Valid values: fully qualified domain name or IP address

logPruningEnabled

Specifies whether log file pruning is enabled or disabled.

Default: true

Valid values: true, false

logPruningMaxTotalLogSize

Specifies the upper limit on how much disk space, in megabytes (MB), the client log files can use. When this limit is exceeded, client log files older than the logPruningMaxLogfileAge are deleted. A value of 0 disables the check for total log size, which causes the old log files to be deleted at the specified logPruningInterval setting.

Default: 0 (disabled)

Valid values: Whole integers greater than or equal to 0

logPruningMaxLogfileAge

Specifies a log file age limit in days. When log pruning cycles run according to the logPruningInterval or logPruningMaxTotalLogSize setting, files older than this age limit are removed. If one log file is younger than the age limit in a subdirectory, all log files in the subdirectory are retained. This retention ensures that all related trace logs are kept intact.

Default: 60

Valid values: Whole integers greater than 0

logPruningInterval

Specifies the log pruning interval in hours. When the logPruningMaxTotalLogSize property is set to 0 (disabled), the time between pruning cycles is controlled by this property.

Default: 1

Valid values: Whole integers greater than 0

preferLocalProcess

This property is not currently used. It is reserved for future use.

preferLocalHost

This property is not currently used. It is reserved for future use.

preferZones

Specifies a list of preferred routing zones. Each specified zone is separated by a comma in the form: preferZones=ZoneA,ZoneB,ZoneC

Default: no value

Valid value: comma-separated list of preferred zones

requestRetryTimeout

Specifies how long to continue processing a request (in milliseconds) after an exception occurs.

Default: -1

Valid values:

• A value of 0 indicates that the request should fail fast and skip over the internal retry logic.
• A value of -1 indicates that the request retry timeout is not set, meaning that the request duration is governed by the transaction timeout. (Default). The following levels of checking the request retry timeout are used to determine the default behavior:
  • Session instance requestRetryTimeout value
  • Client properties file requestRetryTimeout value
  • If neither of the previous values are set, then the lowest value between the transaction timeout value and 30 seconds is selected. For example, if the transaction timeout value has the default value of 10 minutes, then the request times out at 30 seconds. Alternatively, if you set the transaction timeout value to 20 seconds, then the request times out after 20 seconds.
• A value over 0 indicates the request entry timeout value in milliseconds. Exceptions that are not successfully created are returned. Even when exceptions, such as DuplicateException, are tried again, they are also returned when they do not succeed. The transaction timeout is still used as the maximum time to wait.

shuffleBootstrapAddresses

Specifies whether the catalog service addresses are be randomized when used by a client while it is bootstrapping to the data grid. The values must be either true or false.

Default: true

Valid values: true, false

xioTimeout

Specifies the timeout value, in seconds, for outbound socket connection attempts by eXtremeIO. It is also used as a default timeout for internal eXtremeIO logic.

Default: 30

Valid values: number of seconds, any value greater than or equal to 1 second

xioRequestTimeout

Specifies how many seconds any request waits for a response before it gives up. This property influences the amount of time a client takes to fail over if a network outage failure occurs. If you set this property too low, requests might time out inadvertently. Carefully consider the value of this property to prevent inadvertent timeouts.

Default: 30000 (30 seconds)

Valid values: number of milliseconds

Security client properties

General security properties

securityEnabled

Enables WebSphere eXtreme Scale client security. This setting must match with the securityEnabled setting in theWebSphere eXtreme Scale server properties file. If the settings do not match, the client connection to the data grid fails.

Default: false

Valid values: true, false

Credential authentication configuration properties

credentialAuthentication

Specifies the client credential authentication support.

Use one of the following valid values:

Default: Supported

Valid values:

• Never: The client does not support credential authentication.
• Supported: The client supports credential authentication if the server also supports credential authentication. (Default)
• Required: The client requires credential authentication.

authenticationRetryCount

Specifies the number of times that authentication is tried if the credential is expired. If the value is set to 0, attempts to authenticate are not tried again.

Default: 3

Valid values: Integer value greater than or equal to 0

credentialGeneratorAssembly

Specifies the name of the assembly that is used to generate credentials for the WebSphere eXtreme Scale Client for .NET. To specify this property, the credentialAuthentication property must be set to Supported or Required.

Default: no value

Valid values: a valid C# .dll assembly name with version, culture, and other properties included.

Example: IBM.WebSphere.Caching.CredentialGenerator, Version=8.6.0.0, Culture=neutral, PublicKeyToken=b439a24ee43b0816

credentialGeneratorClass

Specifies the name of the class that implements the com.ibm.websphere.objectgrid.security.plugins.CredentialGenerator interface. To specify this property, the credentialAuthentication property must be set to Supported or Required. This class is used to get credentials for clients.

Several built-in classes support this interface; for example:

• com.ibm.websphere.objectgrid.security.plugins.builtins.UserPasswordCredentialGenerator. A user ID and password separated by a space are required for this class.
• com.ibm.websphere.objectgrid.security.plugins.builtins.WSTokenCredentialGenerator

You can also create a custom class, as described in the eXtreme Scale API reference

Default: no value

Valid values: class name

credentialGeneratorProps

Specifies the properties for the CredentialGenerator implementation class. The properties are set to the object with the setProperties(String) method. Specify this property when the credentialAuthentication property is set to Supported or Required, and the credentialGeneratorClass requires properties.

Default: SSL-Supported

Valid values: SSL-Supported, TCP/IP, or SSL-Required

Transport layer security configuration properties

transportType

Specifies the client transport type. The possible values are:

Default: SSL-Supported

Valid values:

• TCP/IP: Indicates that the client only supports TCP/IP connections.
• SSL-Supported: Indicates that the client supports both TCP/IP and Secure Sockets Layer (SSL) connections. (Default)
• SSL-Required: Indicates that the client requires SSL connections.

SSL configuration properties

alias

Specifies the alias name in the keystore. This property is used if the keystore has multiple key pair certificates and you want to select one of the certificates. It is only required if client certificate authentication is configured on the server.

Default: no value

Valid value: alias name in keystore

contextProvider

Specifies the name of the context provider for the trust service. If you indicate a value that is not valid, a security exception results that indicates that the context provider type is incorrect.

Default: no value

Valid values: IBMJSSE2. If you are using a JRE from another vendor, see your vendor documentation for valid JSSE providers. A value must be specified if SSL is used.

clientCertificateKeyStoreLocation

Specifies the Windows keystore location; for example, LocalMachine or CurrentUser. Specifying an invalid value causes a CWOBJ0008E error message in the SystemErr.log file, and client authentication is not completed.

Default: CurrentUser

clientCertificateKeyStore

Specifies the name of the Windows keystore that contains the client certificate. The keystore name might be a Windows predefined store or a custom store. See the following list of some of the Windows defined keystore names:

• My for personal certificates
• Root for trusted root certificate authorities
• AuthRoot for third-party certificate authorities
• CA for intermediate certificate authorities
• TrustedPeople for directly trusted people and resources
• AddressBook for other users
• TrustedPublisher for directly trusted publishers

Specifying an invalid value causes a CWOBJ6209E error message in the SystemErr.log file, and client authentication is not completed.

Default: My

clientCertificateFriendlyName

Specifies the friendly name or alias of the client certificate; for example:

clientCertificateFriendlyName=MyClient Certificate

If you do not set clientCertificateFriendlyName or clientCertificateSubject is set, the client is not authenticated during the SSL handshake.

The certificate must exist in the specified keystore. If the keystore does not exist, the CWOBJ6208E error message occurs in the SystemErr.log file, and client authentication is not completed.

For successful SSL negotiation, the certificate must be defined with a private key; otherwise, the error CWOBJ6206E occurs in the SystemErr.log file, and client authentication is not completed.

clientCertificateSubject

Specifies the full X.500 subject of the client certificate. The value must exactly match the certificate subject value, which includes any white space; for example:

clientCertificateSubject=CN=MyClient, OU=MyOU, O=MyO

When this property is set, clientCertificateFriendlyName is ignored. If you do not setclientCertificateFriendlyName or clientCertificateSubject, the client is not authenticated during the SSL handshake.

The certificate must exist in the specified keystore; otherwise, the error CWOBJ6207E occurs in the SystemErr.log file, and client authentication is not completed.

For successful SSL negotiation, the certificate must be defined with a private key; otherwise, the error CWOBJ6205E occurs in the SystemErr.log file, and client authentication is not completed.

keyStore

Specifies a fully qualified path to the keystore file. A value must be specified if SSL is used. The keyStore is not used unless client certificate authentication is configured on the server. If client certificate authentication is not used, you can specify the trustStore value for keyStore.

Default: no value

Valid values: fully qualified path to keystore

Important: The keyStore directory path does not support Windows backslashes. If you have used backslashes, you must escape any backslash ( \ ) characters in the path. For example, if you want to use the path C:\opt\ibm, enter C:\\opt\\ibm in the properties file. Windows directories with spaces are not supported.

Example: etc/test/security/client.private

keyStorePassword

Specifies the string password to the keystore. A value must be specified if SSL is used. You can encode this value or use the actual value.

keyStoreType

Indicates the type of keystore. A value must be specified if SSL is used. If you indicate a value that is not valid, a runtime security exception occurs.

Default: no value

Valid values: JKS, JCEK, PKCS12, and so on.

protocol

Indicates the type of security protocol to use for the client. Set this protocol value based on which security provider you use. If you indicate a value that is not valid, a security exception results that indicates that the protocol value is incorrect. A value for protocol must be specified if SSL or TLS is used. If you are using a JRE from another vendor, see your vendor documentation for valid protocols.

Default:SSL_TLS. When you specify this default value, the server accepts either the SSL or TLS protocol from the client.

Valid values: When the IBM Runtime Environment is used, the following values are valid: SSL, SSLv3, TLS, TLSv1, , and SSL_TLS.

Valid values: SSLv2, SSLv3, TLS or Default (SSLv3 or TLS1.0)

publicKeyFile

Specifies a fully qualified path name to a file that contains the exported public key from the server.

Example: c:\tmp\wxs\serverA.cer

trustStoreType

Indicates the type of truststore. A value must be specified if SSL is used. If you indicate a value that is not valid, a runtime security exception results.

Valid values: JKS, JCEKS, PKCS12, and so on.

trustStore

Specifies a fully qualified path to the truststore file. A value must be specified if SSL is used.

Example: etc/test/security/server.public

trustStorePassword

Specifies a string password to the truststore. You can encode this value or use the actual value. A value must be specified if SSL is used.