Administer data grids


  1. Administer data grids
  2. Create simple data grids
  3. Create session persistence to a data grid
  4. Create dynamic cache data grids
  5. Configure the maximum capacity of a data grid
  6. Secure data grids
  7. Clear data grids
  8. Invalidate data
  9. Remove data grids
  10. Administer with the xscmd utility


Administer data grids

You can create three different types of data grids:


Create simple data grids

Use simple data grids, with WebSphere Application Server or stand-alone Java applications, to perform create, retrieve, update and delete operations.

Key-value pairs are stored in-memory, reducing expensive database queries. The keys can be of any existing Java type, such as...

Values can be any serializable object type. Every time data is needed, the simple data grid on the appliance is checked first. If the appliance does not have the data, the data is retrieved from the database and inserted into the simple data grid. You can create a simple data grid by writing an application that uses the ObjectMap API.

  1. Create the simple data grid. In the user interface, click...

      Data Grid | Simple Data Grid

    Click the add icon ( ) and specify a name for the simple data grid to create.

    The following characters cannot be used in the name of the data grid:

      ^ . \\ / , # $ @ : ; \ * ? < > | = + & % [ ] " "

  2. Download the objectgrid.xml file for your Simple Data Grid.

    Click the download icon () and save the file to the local file system.

  3. Create a Java application using the ObjectMap API that accesses the data grid.

  4. Configure security sending data to the data grid.

  5. Configure replicas...

      Data Grid | Simple Data Grid | Show advanced attributes

    Replicas are created only when the appliance is in a collective. If the number of appliances in the collective is n, the maximum number of replicas is n-1.

  6. Configure a capacity limit for the data grid.

  7. Configure a time to live evictor for a Simple Data Grid.

  8. Monitor the data grid in the DataPower XC10 appliance user interface.


Configure a TTL evictor for a Simple Data Grid

When you create a Simple Data Grid, a default (static) map and a set of dynamic maps are created. By default, no time to live evictor is configured.

To set a TTL value using...

To change default behavior so that a TTL evictor is enabled for a default map...

  1. In the user interface, click...

      Data Grid | Simple Data Grid | data_grid_name | Show advanced attributes

  2. In the Evictor for map named list box, select an evictor type.

    Selecting an evictor type to other than NONE enables TTL for a default map.

  3. Specify a value in the box...

      Evict data from time to live maps after

    Default is 3600 seconds. A value of 0 turns off TTL eviction for the entire grid.

  4. Click Apply Changes to save.

    You are warned about data loss once the grid restarts.


Examples

Evictor type TTL Notes
NONE 3600 Entries evicted after 1 hour for dynamic maps ending in *.CT, *.LUT, and *.LAT.
Creation Time 3600 Entries evicted after 1 hour for dynamic maps ending in *.CT, *.LUT, and *.LAT.
The default map evicts entries 1 hour after the creation time.
Last updated time 4800 Entries evicted after 80 minutes for dynamic maps ending in *.CT, *.LUT, and *.LAT.
The default map evicts entries 80 minutes after the last time the entry was updated.
NONE 0 TTL eviction is turned off for all maps (default and dynamic) for this grid.
Last access time 0 TTL eviction is turned off for all maps (default and dynamic) for this grid.


Evictors

Evictors remove data from the data grid. You can configure an evictor for a dynamic map and a default map on a simple grid.


Evictor types

The evictor removes entries based on a time to live concept. You can select an evictor that is based on the time it was created, on the time it was last accessed, or updated. By default, an evictor is created with a dynamic map.


Create session persistence to a data grid

Before setting WAS session persistence to use the XC10 data grids...

Only sessions that use cookies as the session tracking mechanism can be saved to the data grid. You cannot persist sessions that use URL rewriting as a session tracking mechanism.


Configure session management when you are installing a WAS application

  1. In the WAS admin console, click...

      Applications | New application | New Enterprise Application

    Choose...

      Detailed path for creating the application

    ...and complete the initial wizard steps.

  2. In the eXtreme Scale session management settings step of the wizard, configure the data grid to use.

    For the Manage session persistence by field, choose...

      WebSphere DataPower XC10 appliance

    Enter the information about the appliance and the data grid on the appliance to use. You can either create a new data grid or use an existing data grid that you have already configured on the appliance.

    To save the sessions in an existing data grid on the appliance, know the name of the data grid to use. You also have the option to create a new data grid on the appliance when you configure the application.

    To create a session data grid before configuring the application

      Data Grid | Session

    Click the add icon ( ) and specify a name for the session data grid to create.

  3. Complete the wizard steps to finish installing your application.

You can also install the application with a wsadmin script. In the following example, the -SessionManagement parameter creates the same configuration that you can in the administrative console:


Configure session management on an existing application

  1. In the WAS administrative console, click...

      Applications | Application Types | WebSphere enterprise applications | application_name | Web Module properties | Session management | eXtreme Scale session management settings

  2. Update the fields to enable session persistence to a data grid.

You can also update the application with a wsadmin script.In the following example, the -SessionManagement parameter creates the same configuration that you can in the administrative console:

The :!: characters that are passed are used as delimiters. The values that are passed are:

When you save the changes, the application uses the configured data grid for session persistence on the appliance.


Configure session management on an existing server

  1. In the WAS administrative console, click...

      Servers | Server Types | WebSphere appservers | server_name | Session management | eXtreme Scale session management settings

  2. Update the fields to enable session persistence.

You configure session management on an existing server with the following wsadmin tool commands:

AdminTask.configureServerSessionManagement('[
    -nodeName my_node 
    -serverName server1 
    -enableSessionManagement true 
    -sessionManagementType XC10SessionManagement 
    -XC10SessionManagement [-applianceIdentifier myserver.ibm.com 
                            -userName xcadmin
                            -password ******** 
                            -gridName myTestGrid]]')

When you save the changes, the server now uses the configured data grid for session persistence with any applications that are running on the server.

If the entire data grid that is hosting the application session data is unreachable from the web container client, the client instead uses the base web container in WAS for session management. The data grid might be unreachable in the following scenarios:

The least recently used sessions are invalidated from the web container session cache. If the data grid on the appliance becomes available, sessions that were invalidated from the web container cache can retrieve data from the remote data grid and load the data into a new session. If the entire data grid on the appliance is not available and the session is invalidated from the session cache, the user session data is lost. Because of this issue, do not shut down entire production data grid when the system is running under load.

When you configure this scenario, the security credentials for the IBM WebSphere DataPower XC10 appliance are automatically stored in the WAS configuration. If you change the credentials for the data grid after the initial configuration, the WAS no longer has the correct credentials. You can reset the credentials by applying the eXtreme Scale session management settings again.


Configure HTTP session manager with WebSphere Portal

You can persist HTTP sessions from WebSphere Portal into a data grid. Your WebSphere eXtreme Scale Client and WebSphere Portal environment must meet the following requirements:

Introducing WebSphere DataPower XC10 appliance into a WebSphere Portal environment can be beneficial in the following scenarios:

Although the following scenarios introduce benefits, increased processor usage in the WebSphere Portal tier can result from introducing WebSphere DataPower XC10 appliance into the environment.

  1. Configure the wps WebSphere Portal application and any custom portlets to enable the sessions to be stored in the data grid.

  2. If TLS/SSL is configured for the WebSphere Portal server and for the appliance, configure the TLS/SSL truststores.

    • If the resulting outbound communication from the portal server to the appliance uses TLS/SSL, add the appliance certificate to the WAS configuration. Use...

        cd was_root/bin
        wsadmin.sh -conntype SOAP 
                   -port <PORTAL_SERVER_SOAP_PORT> 
                   -lang jython 
                   -user wpsadmin 
                   -password wpsadmin 
                   -f addXC10PublicCert.py

    • If the resulting inbound communication from the appliance to the portal server uses TLS/SSL, update the appliance truststore to include the public certificates for the portal server. Updating the truststore enables communication between the appliance and portal.

    1. Extract the public key of the Portal Server personal certificate. Use the IKEYMAN utility. This utility creates a .arm file.

    2. Download the public truststore for the appliance.

    3. Use the iKeyman utility to update the truststore.jks file that you extracted from the appliance with the public Portal Server certificate in the .arm file.

    4. Upload the updated truststore file to the appliance. Click Submit TLS settings after you upload the truststore. The collective automatically restarts when you submit the TLS settings and the new truststore is added to the other appliances in the collective.

  3. Restart the portal servers.

You can access the WebSphere Portal Server, and HTTP session data for the configured custom portlets is persisted to the data grid.

If the entire data grid that is hosting the application session data is unreachable from the web container client, the client instead uses the base web container in WAS for session management. The data grid might be unreachable in the following scenarios:

The number of session references kept in memory, specified by sessionTableSize parameter, is still maintained when the sessions are stored in the base web container. The least recently used sessions are invalidated from the web container session cache when the sessionTableSize value is exceeded. If the remote data grid becomes available, sessions that were invalidated from the web container cache can retrieve data from the remote data grid and load the data into a new session. If the entire remote data grid is not available and the session is invalidated from the session cache, the user.s session data is lost. Because of this issue, you should not shut down the entire production remote data grid when the system is running under load.


Create dynamic cache data grids

Use the appliance to store data from your WAS dynamic cache. By setting up this capability, you can enable applications that are written with the Dynamic Cache API or applications using container-level caching (such as servlets) to use the features and performance capabilities of the appliance.

When you configure the dynamic cache provider in WAS to use DataPower XC10 appliance, the cache data is stored outside of the WAS topology. All the cache data is stored in the appliance. The memory that was being used for caching in the appservers can be used for other purposes.

  1. Review the following IBM WebSphere Commerce documents:

  2. Install the WebSphere eXtreme Scale Client in the WAS configuration.

  3. If the appliance has transport layer security enabled, enable global security in the WAS admin console.

  4. Specify the catalog service running on the appliance in WAS.

    The catalog service enables the WAS dynamic cache configuration to communicate with the DataPower XC10 appliance. You can configure the catalog service in the WAS admin console by creating a catalog service domain.

  5. Create the Dynamic Cache data grid on the DataPower XC10 appliance.

    To use the dynaCfgToAppliance to create the Dynamic Cache data grid, log on to the dmgr host machine and run...

    ...where...

    IP_address IP address of the appliance
    cache_name JNDI name of the dynamic cache. If there slashes (/) in the name, the slashes are converted by the script to a dash for the name of the Dynamic Cache data grid in Appliance. For example, if dynamic cache name is services/cache1, the data grid created on the appliance is named services-cache1
    appliance_admin Administrator ID for logging in to the DataPower XC10 appliance user interface.
    admin_pw Administrator password for logging in to the DataPower XC10 appliance user interface.
    SOAP_port (Optional) SOAP port for the dmgr if you are using a port number other than the default of 8879.
    /path/to/soap.client.props (Optional) This file enables SOAP security and specifies the user name and password to administer the WAS dmgr.

      com.ibm.SOAP.securityEnabled=true
      com.ibm.SOAP.loginUserid=
      com.ibm.SOAP.loginPassword=<

    The script...

    • Creates the data grid on the appliance

    • Set the appliance ID and password credentials with the following custom properties:

      • xc10.<data_grid_name>.userid
      • xc10.<data_grid_name>.password

      If you run the script again after the initial configuration, the custom properties are updated.

    To create the dynamic cache data grid using the user interface

    1. Click...

        Data Grid | Dynamic Cache

    2. Create a WAS cache instance to configure with the DataPower XC10 appliance.

  6. Optional: Configure the baseCache instance to use the appliance.

    Create the following custom properties on the JVM. When you configure the baseCache instance, all of the cache instances in the JVM also have the properties set. You can override the values of the baseCache custom properties by creating custom properties on the individual cache instances.

      Resources | Cache instances | cache_instance_type | cache_instance_name | Custom properties

    Set...

    • xc10.<data_grid_name>.userid
    • xc10.<data_grid_name>.password

    The value of the <data_grid_name> in each custom property is the JNDI name of the data grid, replacing any slashes (/) with dashes. For example, with the previous example, the custom property names are...

    • xc10.services-cache1.userid
    • xc10.services-cache1.password

    The values should be set to a user ID and password that can access the data grid in the DataPower XC10 appliance configuration. You can encode the password using...

      DMGR_HOME/bin/encodePassword

  7. Enable the DataPower XC10 appliance as the dynamic cache provider.

    Select the WebSphere eXtreme Scale dynamic cache provider in the administrative console.

  8. Configure the replication setting for the cache.

    You can enable cache replication in the WAS Version 7.0 administrative console.

  9. Set the topology custom property on the cache instance to modify.

      com.ibm.websphere.xs.dynacache.topology = remote

  10. Configure WAS v6.1 specific settings...

    1. Enable the DataPower XC10 appliance as the dynamic cache provider.

      Configure the dynamic cache provider for a cache instance by setting the cache instance custom property...

        com.ibm.ws.cache.CacheConfig.cacheProviderName

      To set the provider to use the DataPower XC10 appliance...

        com.ibm.ws.objectgrid.dynacache.CacheProviderImpl

      To set the provider back to the default WAS dynamic cache provider for a specific cache instance, set the name of the custom property to default. If you are configuring the baseCache instance to use the DataPower XC10 appliance cache provider, you might need to set the property to default on your other cache instances if you want them to use the default cache provider.

    2. Configure the replication setting for the cache.

      Create a replication domain using either...

  11. (Optional) Configure security

  12. Configure replicas.

    Replicas ensure that the data grid data is available if the primary copy fails. To configure replicas, on the appliance click...

      Data Grid | Dynamic Cache | Show advanced attributes

    Replicas are created only when the appliance is in a collective. If the number of appliances in the collective is n, the maximum number of replicas is n-1. Therefore if you configure three replicas, but you only have two appliances in the collective, only one replica is created. Additional replicas are created if you add appliances to the collective. Set the number of replicas to the ideal amount to have, so that as appliances join the collective, new replicas can be created. The data grid content is cleared when you edit the number of replicas.

  13. Configure a capacity limit for the data grid

  14. Monitor the dynamic cache data grid in the DataPower XC10 appliance user interface.

See also...


Create catalog service domains in WAS

With WebSphere DataPower XC10 appliance, you define catalog service domains to establish connections with the catalog servers that are running on the appliance. Creating this configuration is required for dynamic cache data grids only.

By creating a catalog service domain, you are defining a highly available collection of catalog servers. By configuring a catalog service domain, you are establishing connections to the catalog servers that are running on the WebSphere DataPower XC10 appliance. This catalog service domain represents the group of catalog servers that are running on the appliances in your collective.

  1. Create the catalog service domain.

    1. In the WAS administrative console, click...

        System administration | WebSphere eXtreme Scale | Catalog service domains | New

    2. Define a name, default value, and JMX authentication credentials for the catalog service domain.

    3. Add catalog server endpoints.

      To view the catalog servers that are running in the collective, click...

        Collective | Members | member_name

      The Catalog servers field lists the catalog servers that are running in the collective. Specify the endpoints with IP addresses or fully-qualified host names.

      Client port Not required for connections to catalog servers running on the appliance.
      Listener port 2809

    4. Test the connection to the catalog servers within the catalog service domain.

        System administration | WebSphere eXtreme Scale | Catalog service domains | catalog_service_domain | Test connection

      When you click this button, all of the defined catalog service domain end points are queried one by one, if any one end point is available, returns a message that indicates that the connection to the catalog service domain was successful.


Catalog service domain administrative tasks

Use the Jacl or Jython scripting languages to manage catalog service domains in your WAS configuration. With WebSphere DataPower XC10 appliance, you define catalog service domains to establish connections with the catalog servers that are running on the appliance. Creating this configuration is required for dynamic cache data grids only.


List all administrative tasks

To get a list of all of the administrative tasks associated with catalog service domains...


createXSDomain

Register a new catalog service domain...

Argument Description
-name (required) Name of the catalog service domain to create.
-default Set true to make catalog service domain default for the cell.
-properties Custom properties for the catalog service domain.


defineDomainServers step arguments

Argument Description
name_of_endpoint Name of the catalog service endpoint.

Existing appservers The name of the endpoint must be in the following format:

    cell_name\node_name\server_name
Remote servers Host name of the remote server. You can have the same name for multiple endpoints, but the client port values must be unique for each endpoint.

custom_properties Custom properties for the catalog service domain endpoint. If you do not have any custom properties, use a set of double quotes ("") for this argument.
endpoint_ports Port numbers for the catalog service domain endpoint. The ports must be specified in the following order: <client_port>,<listener_port>

Client Port

Port used for communication between the catalog servers in the catalog service domain. Required for catalog servers that are running in WAS processes only and can be set to any port that is not being used elsewhere.

Listener Port

Port used for communication with clients.

Required for remote endpoints and must match the value used when the catalog service was started. The listener port is used by clients and containers to communicate with the catalog service.

For WebSphere DataPower XC10 appliance remote endpoints, use the value 2809 for the appliance remote endpoints.

Return value: :

Usage

Batch mode requires correct formatting of the command entry. Consider using interactive mode to ensure the values that you enter are processed correctly. When you use batch mode, you must define the -defineDomainServers step arguments using a specific array of properties. This array of properties is in the format name_of_endpoint custom_properties endpoint_ports. The endpoint_ports value is a list of ports that must be specified in the following order: <client_port>,<listener_port>.

Interactive...


deleteXSDomain

Delete a catalog service domain.

Required parameters:

-name
Name of the catalog service domain to delete.

Return value: :

Usage

Interactive...


getDefaultXSDomain

Return the default catalog service domain for the cell.

Required parameters: None

Return value: : The name of the default catalog service domain.

Usage

Interactive...


listXSDomains

Return a list of the existing catalog service domains.

Required parameters: None

Return value: : A list of all of the catalog service domains in the cell.

Usage

Interactive...


modifyXSDomain

Modify an existing catalog service domain.

Batch mode requires correct formatting of the command entry. Consider using interactive mode to ensure the values that you enter are processed correctly. When you use batch mode, you must define the -modifyEndpoints, -addEndpoints and -removeEndpoints step arguments using a specific array of properties. This array of properties is in the format name_of_endpoint host_name custom_properties endpoint_ports. The endpoint_ports value is a list of ports that must be specified in the following order:

modifyXSDomain command arguments...

Argument Description
-name (required) Name of the catalog service domain to edit.
-default If set to true, specifies that the selected catalog service domain is the default for the cell. (Boolean)
-properties Custom properties for the catalog service domain.

Table 4. modifyEndpoints step arguments
Argument Description
name_of_endpoint Name of the catalog service endpoint.

  • Existing appservers: The name of the endpoint must be in the following format: cell_name\node_name\server_name

  • Remote servers: Host name of the remote server.You can have the same name for multiple endpoints, but the listener port values must be unique for each endpoint. This value must be a fully-qualified domain name if you are configuring an appliance.
endpoint_ports Port numbers for the catalog service domain endpoint. The endpoints must be specified in the following order: <client_port>,<listener_port>

Client Port

Port used for communication between the catalog servers in the catalog service domain. Required for catalog servers that are running in WAS processes only and can be set to any port that is not being used elsewhere.

Listener Port

Port used for communication with clients. Required for remote endpoints and must match the value used when the catalog service was started. The listener port is used by clients and containers to communicate with the catalog service.

For WebSphere DataPower XC10 appliance remote endpoints: Use the value 2809 for the appliance remote endpoints.


addEndpoints step arguments

Argument Description
name_of_endpoint Name of the catalog service endpoint.

  • Existing appservers: The name of the endpoint must be in the following format:

      cell_name\node_name\server_name

  • Remote servers: Host name of the remote server. You can have the same name for multiple endpoints, but the listener port values must be unique for each endpoint. This value must be a fully-qualified domain name if you are configuring an appliance.

custom_properties Custom properties for the catalog service domain endpoint. If you do not have any custom properties, use a set of double quotes ("") for this argument.
endpoint_ports Port numbers for the catalog service domain endpoint. The endpoints must be specified in the following order:

    <client_port>,<listener_port>

Client Port Port used for communication between the catalog servers in the catalog service domain. Required for catalog servers that are running in WAS processes only and can be set to any port that is not being used elsewhere.
Listener Port Port used for communication with clients. Required for remote endpoints and must match the value used when the catalog service was started. The listener port is used by clients and containers to communicate with the catalog service. For WebSphere DataPower XC10 appliance remote endpoints: Use the value 2809 for the appliance remote endpoints.

Table 6. removeEndpoints step arguments
Argument Description
name_of_endpoint Name of the catalog service endpoint to delete.

Return value: :

Usage

Interactive...


testXSDomainConnection

Test the connection to a catalog service domain.

Required parameters:

-name
Name of the catalog service domain to which to test the connection.

Optional parameters

-timeout
Maximum amount of time to wait for the connection, in seconds.

Return value: : If a connection can be made, returns true, otherwise, connection error information is returned.

Usage

Interactive...


testXSServerConnection

Test the connection to a catalog server. This command works for both stand-alone servers and servers that are a part of a catalog service domain.

Required parameters:

host
Host on which the catalog server resides.
listenerPort
Listener port for the catalog server.

Optional parameters

timeout
Maximum amount of time to wait for a connection to the catalog server, in seconds.

Return value: :

Usage

Interactive...


Configure the maximum capacity of a data grid

By default, data grids do not have a configured maximum capacity limit. You can configure a maximum capacity for any data grid type:

Capacity limits are enforced by comparing the total size of all primary data in the grid to the configured capacity limit. Capacity used by replica copies of data is not counted.

The limit is not a guarantee of an allocated amount of space for the data grid. A data grid might not be able to reach its configured capacity limit if the collective does not have the capacity to store the data. Reasons for insufficient capacity in the collective might be a high capacity limit on the data grid, or capacity that is consumed by other data grids in the collective.

When the capacity limit for a particular data grid is breached, the grid handles insert operations in one of the following ways:

To configure data grid capacity limits...

  1. In the user interface, click...

      Data Grid | data_grid_type | data_grid_name | Show advanced attributes

  2. Select Limit the amount of capacity for this data grid.

  3. If you are setting the maximum capacity for a simple data grid and want the grid to accept new insert operations (instead of rejecting them) at the expense of least recently used data entries, then select...

      Use least recently used (LRU) eviction for this data grid

    Click Apply Changes to save. You are warned that the data in the grid will be lost to complete the restart.

  4. View the current capacity consumption to determine the maximum capacity to define for the selected data grid.

    In this chart, the current data grid that is being configured, MyGrid, is currently using 900 megabytes of capacity. It has a currently configured capacity limit of 2000 megabytes. At the collective level, the total capacity of the collective is 4000 megabytes. In addition, the total of all the configured limits on the capacity-limited data grids is 3400 megabytes. Those grids are currently using 2900 megabytes. Finally, there is at least one data grid in the collective that does not have a capacity limit defined. These data grids without defined capacity limits are consuming approximately 900 megabytes.

  5. Enter a value for the limit of primary data consumption in MB.

    When you press enter, the potential maximum capacity consumption of the primary and replica data displays. This number varies based on the number of replicas that you have defined. However, remember that the number of replicas is limited by the number of appliances in the collective. If you have four replicas defined, and three appliances in the collective, your collective contains one primary and two replicas.

  6. Click Apply changes to save the configuration. You do not need to restart the data grid to activate the new limit.


Capacity Limit Example 1: Multiple data grids

Data grids A, B, and C are defined in a collective with a total capacity of 600 gigabytes of storage. No replicas are defined on any of the data grids. Data grid A has a capacity limit of 100 gigabytes. Data grid B has a capacity limit of 50 gigabytes. Data grid C has a capacity limit of 200 gigabytes. In this scenario, at least 250 gigabytes of unused capacity are always available in the collective. The total size of the three data grids cannot grow beyond 350 gigabytes.


Capacity Limit Example 2: Replicas

Data grid A is defined in a collective of two appliances. Data grid A has one synchronous and two asynchronous replicas, for a total of three replicas. The grid capacity limit is defined as 100 megabytes. Initially the maximum capacity consumption of this grid is 200 megabytes. Because the collective has only two appliances, one primary and one replica copy of the data exist. The primary data grid can use up to 100 megabytes. The replica grows at the same rate as the primary data grid, resulting in a maximum total consumed capacity of 200 megabytes. If a third appliance is added to the collective, a second replica copy of the data is placed. The maximum consumption of the grid becomes 300 megabytes, from the one primary plus two replicas.


Capacity Limit Example 3: Data grids with no capacity limit

Data grids A, B, and C are defined in a collective with a total capacity of 600 gigabytes of storage. Data grid A has a limit of 100 gigabytes. Data grid B has a limit of 50 gigabytes. Data grid C has no capacity limit. No replicas are defined for any of the three grids. Because data grid C has no limit, the data grid could potentially consume the entire 600 gigabytes of available capacity. As a result, data grid A and data grid B would not be able to insert any data. Any data that data grid A or data grid B inserted remains, but the data grids are not guaranteed to be able reach their capacity limits. Data grid C is guaranteed to have at least 450 gigabytes available to consume because the only other data grids on the system cannot consume more than a total of 150 gigabytes out of the 600 gigabytes of capacity. This 450 gigabyte calculation ignores any capacity that is consumed by the replica data. If two or more unlimited data grids exist in the collective, the potential capacity of any specific data grid is not guaranteed.


Secure data grids

After you create the data grids, the security of the data grid is disabled by default. You can change the security settings for a data grid to restrict access to a certain user or group of users.

When you change the security settings for a data grid, the data grid automatically restarts. When the data grid is restarted, any data that is in the data grid is lost. Configure the security for the data grids before you begin to save data in the data grid. Communication through the REST gateway is always secure, even if you do not have security enabled on the data grid.

  1. In the user interface, navigate to...

      Data Grid | data_grid_type | data_grid_name

  2. Enable security or authorization for the data grid. Click Enable security to enable any user that has access to the user interface to access the data grid. To further restrict access, click...

      Enable authorization

    With authorization enabled, you can specify a list of users or user groups in the Access granted to list. When enable authorization is selected, only users that are listed in this access list can access the data grid data. You can assign the following access to users or user groups by clicking the name of the default access type that is displayed in the user interface:

    read The user or user group can read or query data from the data grid.
    write The user or user group can read, query, and write data to the data grid.
    create The user or user group can read, query, write, insert, and create dynamic maps in the data grid.
    all The user or user group can read, query, write, insert, create dynamic maps, remove, and invalidate data from the data grid. Appliance administrators have all permission by default.

    When you change the security and authorization settings, there is a timeout value of five minutes.

    Authentication timeout If password is changed for user that has authenticated to the data grid, the original credential is still valid for up to five minutes.
    Authorization timeout If permissions are removed that has authenticated to the data grid, that user continues to have the permission for up to five minutes. If you add a permission to a user, the user gets the permissions immediately.


Clear data grids

You can permanently delete all of the entries in a data grid. You can clear the data grid to remove stale information or test entries.

  1. In the user interface, click...

      Data Grid | data_grid_type | data_grid_name

  2. Click the clear grid icon () to delete all of the data grid entries. Confirm to remove all of the entries in the data grid.

  3. You can verify that the data grid entries were deleted in the user interface. Click...

      Monitor | Individual Data Grid Overview | data_grid_name | view the Used capacity vs. Number of cache entries chart

    For simple data grids and session data grids, the number of entries in the data grid should approach zero. However, with a dynamic cache data grid, several entries remain in the data grid. These data grid entries contain the configuration information for the dynamic cache data grid.


Invalidate data

Use the query interfaces in the monitoring console and in the xscmd utility to retrieve small sets of keys from a map and invalidate sets of data.

Use the console or the xscmd utility to query data grid contents. You can query the data by running a regular expression on the data key. You can then use the same query to invalidate data.

A regular expression is a structured string used to match other strings. Some examples of common regular expressions follow:

Regular expression Description
. Finds any one character.
.* Finds any one character zero or more times.
A.* Finds all keys that start with "A".
.*A Finds all keys that end with "A".
A? Finds "A", zero or one time.
A* Finds "A", zero or many times.
A+ Finds "A", one time or many times.
A?B*C+ Finds any one character, followed by zero or one A, followed by zero or many Bs, followed by one or many Cs
[ABC].* Finds keys that start with the letters "A", or "B", or "C".
.*ABC.* Finds keys with the string "ABC" somewhere in the string.
(ABC|DEF).* Finds keys that start with the string "ABC" or "DEF".

See the java.util.regex.Pattern API documentation for the full regular expression syntax.


Query or invalidate data with the console

  1. Go to the query page in the console. In the user interface, click...

      Data Management | Query Data Grid Contents

  2. Search or filter the data in the map. Use one of the following options to search or filter the data:

    • Type a regular expression in the field and click the Search button (). A list of keys that match the regular expression displays. The list of data could be a subset of all of the matching data.

    • To filter the results on a set of partitions, click the Filter button (). You can then type a regular expression and choose a range of partitions on which you want to filter the results.

  3. Invalidate data. When you invalidate the data, the data is permanently removed from the data grid.

    Selected keys

    You can select keys from the table to invalidate. You can either click entries individually or click the select all checkbox, which selects a maximum of 500 entries that are in the table. When you have the entries selected to remove, click...

      Invalidate | Selected keys

    All keys matching query

    You can also invalidate all the data that matches your regular expression. Using this option deletes all data in the data grid that matches the regular expression, not just the maximum of 500 entries that is displayed in the console. To invalidate entries with the selected regular expression, click...

      Invalidate | All keys matching query


Query or invalidate data with the xscmd utility

Query data:

    xscmd.sh -c findbykey 
             -g <data_grid> 
             -m <map> 
             -fs <find_string> 
            [-fp <partitionid>]

Include the data grid, map, and regular expression for the find string value. You can also filter on the partition ID. The result returns a subset of the entire query.

Invalidate data:

Include the -inv argument in the command to invalidate the data that is selected by the query.

    xscmd -c findbykey 
          -g <data_grid> 
          -m <map> 
          -fs <find_string> 
         [-fp <partitionid>] -inv

Include the data grid, map, and regular expression for the find string value. You can also filter on the partition ID. When you run the invalidation, all matching values are invalidated, not just the small set that is returned by the query.

If your regular expression starts with the characters .*, the characters might not process correctly when you run the command. To resolve this issue, format your regular expression in one of the following ways:

To look for all entries in the Grid1 data grid and Map1 map, run...

...which returns...


Remove data grids

To clear the data grid data, you can remove the data grid and then recreate the data grid.

  1. In the user interface, click...

      Data Grid | data_grid_type

    Select the data_grid_name to delete.

  2. Click the remove icon () to begin the removal process.

    A message box is displayed requesting confirmation that this data grid can permanently be removed. Click OK to confirm the removal.

  3. You can monitor the removal of the data grid in the Tasks view.


Administer with the xscmd utility

  1. Start the appliance

  2. Install the WXS client

  3. Verify JAVA_HOME environment variable is set to use the WXS runtime.

  4. Verify the IP address and port number of active catalog servers. From the appliance interface

      Collective | Members | member_name

  5. From the appliance user interface, download the active truststore...

    The default truststore file is xsatruststore.jks. The default password is: xc10pass.

  6. If client authentication is enabled, on the client installation, set environment variables.

      CLIENT_AUTH_LIB=/path/to/security/JAR
      export CLIENT_AUTH_LIB

  7. Connect the xscmd utility to the appliance.

      cd $WAS_HOME/bin
      xscmd.bat -ts xsatruststore.jks 
                -tst jks 
                -tsp xc10pass 
                -user xcadmin 
                -pwd xcadmin 
                -cep myxc10.mycompany.com  
                -prot TLS 
                -cxpv IBMJSSE2 
                -tt TCP/IP [additional parameters]

  8. Display general help...

      ./xscmd.sh -h

  9. Display list of all commands...

      ./xscmd.sh -lc

  10. Display help for a specific command...

      ./xscmd.sh -h command_name

  11. Display a list of the command groups...

      ./xscmd.sh -lcg

  12. Display a list of the commands within a command group...

      ./xscmd.sh -lc command_group_name

  13. Run commands that connect to specific catalog servers.

      ./xscmd.sh -c <command_name> -cep cathost:catport(,cathost:catport)

    Do not use the following commands in a WebSphere DataPower XC10 appliance environment:

  14. Optional: Set a timeout value.

    Use the -to or --timeout option as a global parameter on any command. Number of seconds before timing out when connected to catalog servers. If you are connecting to a catalog server that might be unavailable due to operating system and other network timeouts, using this option can be useful to reduce the wait to a controlled time. The default is 30 seconds.


Configure security profiles for the xscmd utility

By creating a security profile, you can use saved security parameters to use the xscmd utility with secure environments.

To save a security profile, run xscmd with either...

The profile can contain settings for...

Adding the parameter to your xscmd command saves the following parameters:

The ProfileManagement command group in the xscmd utility contains commands for managing security profiles.

Security profiles are saved in...

Do not include the .properties file name extension on the profile_name parameter. This extension is automatically added to the file name.

To use a saved security profile, add the -sp profile_name or --securityProfile profile_name parameter to the command you are running. For example:

  • List commands in the ProfileManagement command group.

      xscmd -lc ProfileManagement

  • List the existing security profiles.

      xscmd -c listProfiles -v

  • Display the settings that are saved in a security profile.

      xscmd -c showProfile -pn profile_name

  • Remove an existing security profile.

      xscmd -c RemoveProfile -pn profile_name.


    See also

    1. WebSphere eXtreme Scale Version 7.1 API documentation