Home

xsadmin - WebSphere eXtreme Scale


WXS samples

Samples from the WebSphere eXtreme Scale Samples Gallery...

Sample Description
Asynchronous Service Framework Asynchronous processing of messages.
BSON serializer Write a WXS serializer that uses Binary JSON (BSON) to describe and serialize objects.
Client authentication security Configure authentication requiring the client to provide valid credentials before the server gives any grid access.
Create dynamic maps Maps grid has already been initialized. Use templates to retrieve maps.
Get started with WXS Basic operation in a WebSphere Application Server environment.
Get started with Spring Spring framework integration. Sample contains shell and batch scripts designed to start a simple grid.
Google protocol buffer serializer Write a WXS serializer. Uses Google protocol buffers to describe and serialize objects.
Liberty profile Airport sample Introduction to WXS installed in the WAS V8.5 Liberty profile environment. Sample shows how large amounts of data, in this case, information about thousands of airports worldwide, can be stored.
Multimaster replication Quick introduction to multi-master (AP) replication.
OSGi framework Install and run a WXS data grid in the Eclipse Equinox OSGi framework. Sample includes several plug-in bundles that illustrate the best practices for developing dynamic WXS plug-in bundles so that the WXS servers can be updated without costly restarts.
Queries with Entity Manager API Use queries in a distributed partitioned map with the EntityManager API.
Run queries in Parallel queries Use Data Grid API with a ReduceGridAgent implementation to run a query over every partition in the grid.
Resource adapter Connect to a WXS data grid in the application with the WXS resource adapter using the Java Transaction API (JTA). This sample helps you install the resource adapter, configure a connection factory, and code samples to connect and add or retrieve objects from your data grid/a>.


Articles with tutorials and examples

Article Features
WebSphere eXtreme Scale Tutorial Partitioning, replication, shards, zones, programming APIs, performance tuning
Building grid-ready applications ObjectMap API, EntityManager API, queries, agents, Java SE and EE, statistics, partitioning, administration and operations, Eclipse
Scalable grid-style computing and data processing EntityManager API, agents
Build a scalable, resilient, high-performance database alternative ObjectMap API, replication, partitioning , administration and operations, Eclipse
Enhance xsadmin for WebSphere eXtreme Scale Administration
Redbook: User's Guide All topics

Oracle Java Serialization API
Build OSGi applications with the Blueprint Container specification
OSGi Bundle Activator API documentation
Spring namespace schema


Free trial

To get started using WebSphere eXtreme Scale, download a free trial version.

After downloading and unzipping the trial version of eXtreme Scale, to get started, read...

...which shows how to create a data grid on several servers, and run some simple applications to store and retrieve data in a grid.


Sample properties files

Server properties files contain settings for running the catalog servers and container servers . You can specify a server properties file for either a stand-alone or WebSphere Application Server configuration. Client property files contain settings for your client.

Sample properties files can be found in: wxs_install_root/properties


Sample: xsadmin utility

xsadmin.sh is officially supported for...

To use set JAVA_HOME. xsadmin.sh uses an implementation of Managed Beans. you can extend using interfaces in the package...

xsadmin source code can be found in...

To display online help...

You must pass in only one of the listed options for the utility to work. If no -g or -m option is specified, xsadmin.sh prints out information for every grid in the topology.


Enable statistics for all of the servers


Display all online containers for a grid

All container information is displayed. An example of the output follows:

Connecting to Catalog service  at localhost:1099

*** Show all online containers for grid - ObjectGridA & mapset - MapSetA

Host: 192.168.0.186
Container: server1_C-0, Server:server1, Zone:false Zone
Partition Shard Type
        0 Primary

Num containers matching = 1
Total known containers = 1
Total known hosts = 1

To obtain this information when TLS/SSL is enabled, start the catalog and container servers with the JMX service port set. To set the JMX service port, you can either use the -JMXServicePort option on the startOgServer script or you can call the setJMXServicePort method on the ServerProperties interface.


Connect to the catalog service and display information about MapA

The size of the specified map is displayed. An example of the output follows:

Connecting to Catalog service  at localhost:1099

****Displaying Results for Grid - ObjectGridA, MapSet - MapSetA*****

*** Listing Maps for server1 ***
 Map Name Partition Map Size Used Bytes (B) Shard Type
 MapA     0         0        0              Primary


Connect to catalog service using a specific JMX port

xsadmin.sh -g ObjectGridA \
           -m MapSetA -mapsizes \
           -fm MapA 
           -ch CatalogMachine 
           -p 6645

The xsadmin sample utility connects to the MBean server running on a catalog server. A catalog server can run as a stand-alone process, WebSphere Application Server process, or embedded within a custom application process. Use the -ch option to specify the catalog service host name, and the -p option to specify the catalog service naming port.

The size of the specified map is displayed. An example of the output follows:

Connecting to Catalog service  at CatalogMachine:6645

*****Displaying Results for Grid - ObjectGridA, MapSet - MapSetA*****

*** Listing Maps for server1 ***
Map Name: MapA  Partition #: 0  Map Size: 0  Shard Type: Primary
Server Total: 0


Connect to a catalog service hosted in a WAS process

The -dmgr option is required when connecting to a catalog service hosted by any WebSphere Application Server process or cluster of processes. Use the -ch option to specify the host name if not localhost, and the -p option to override the catalog service bootstrap port, which uses the process BOOTSTRAP_ADDRESS. The -p option is only needed if the BOOTSTRAP_ADDRESS is not set to the default of 9809.

The stand-alone version of WXS cannot be used to connect to a catalog service hosted by a WAS process.

The size of the specified map is displayed.

Connecting to Catalog service  at localhost:9809

****Displaying Results for Grid - ObjectGridA, MapSet - MapSetA*****

*** Listing Maps for server1 ***
Map Name: MapA  Partition #: 0  Map Size: 0  Shard Type: Primary
Server Total: 0


Display configured and placement of the configuration

xsadmin -placementStatus
xsadmin -placementStatus -g myOG -m myMapSet
xsadmin -placementStatus -m myMapSet
xsadmin -placementStatus -g myOG

You can scope the command to display placement information for the entire configuration, a single data grid, a single map set, or a combination of a data grid and map set. An example of the output follows:

***********Printing Placement Status for Grid - Grid, MapSet - mapSet**************

<objectGrid name="Grid" mapSetName="mapSet">
  <configuration>
    <attribute name="placementStrategy" value="FIXED_PARTITIONS"/>
    <attribute name="numInitialContainers" value="3"/>
    <attribute name="minSyncReplicas" value="0"/>
    <attribute name="developmentMode" value="true"/>
  </configuration>
  <runtime>
    <attribute name="numContainers" value="3"/>
    <attribute name="numMachines" value="1"/>
    <attribute name="numOutstandingWorkItems" value="0"/>
  </runtime>
</objectGrid>

developerWorks: Enhance xsadmin for WebSphere eXtreme Scale


Create a configuration profile for xsadmin.sh

You can save your frequently specified parameters for xsadmin.sh in a properties file. As a result, xsadmin.sh calls are shorter.

Create a basic deployment of WXS that includes at least one catalog server and at least one container server. If you specify both a properties file and a corresponding parameter as a command line argument, the command line argument overrides the properties file value.

  1. Create a configuration profile properties file. This properties file should contain any global properties to use in all your xsadmin command invocations.

    Save the properties file with any name you choose. For example, you might place the file in:

      /opt/ibm/WebSphere/wxs71/ObjectGrid/security/<my.properties>

    Replace <my.properties> the name of your file. For example, you might set the following properties in your file:

    • XSADMIN_TRUST_TYPE=jks
    • XSADMIN_TRUST_PATH=/opt/ibm/WebSphere/wxs71/ObjectGrid/bin/security/key.jks
    • XSADMIN_USERNAME=ogadmin

  2. Run xsadmin.sh with the properties file that you created. Use the -profile parameter to indicate the location of your properties file. Use -v to display verbose output.
    ./xsadmin.sh -l 
                 -v 
                 -password xsadmin 
                 -ssl 
                 -trustPass ogpass 
                 -profile /opt/ibm/WebSphere/wxs71/ObjectGrid/security/<my.properties>
    


xsadmin utility reference

You can pass arguments to xsadmin.sh with two different methods: with a command-line argument, or with a properties file.


xsadmin arguments

You can define a properties file for xsadmin.sh with Version 7.1 Fix 1 or later. By creating a properties file, you can save some of the frequently used arguments, such as the user name. The properties that you can add to a properties file are in the following table. If you specify both a property in a properties file and the equivalent command-line argument, the command-line argument value overrides the properties file value.

Arguments for xsadmin.sh...

Command Line Argument Equivalent Property Name in Properties File Description and valid values
-bp n/a

Indicates the listener port.

Default: 2809

-ch n/a

Indicates the JMX host name for the catalog server.

Default: localhost

-clear n/a

Clears the specified map.

Allows the following filters: -fm

-containers n/a For each data grid and map set, displays a list of container servers .

Allows the following filters: -fnp

-continuous n/a Specify this flag if you want continuous map size results to monitor the data grid. When you run this command with the -mapsizes argument, the map size is displayed every 20 seconds.
-coregroups n/a Display all core groups for the catalog server. This argument is used for advanced diagnostics.
-dismissLink <catalog_service_domain> n/a

Removes a link between 2 catalog service domains. Provide the name of the foreign catalog service domain to which you previously connected with the -establishLink argument.

-dmgr n/a

Indicates if you are connecting to a WebSphere Application Server hosted catalog service.

Default: false

-empties n/a Specify this flag if you want to show empty containers in the output.
-establishLink <foreign_domain_name> <host1:port1,host2:port2...> n/a

Connects the catalog service domain to a foreign catalog service domain. Use the following format:

-establishLink <foreign_domain_name> <host1:port1,host2:port2...>. foreign_domain_name is the name of the foreign catalog service domain, and host1:port1,host2:port2... is a comma-separated list of catalog server host names and Object Request Broker (ORB) ports running in this catalog service domain.

-fc n/a Filters for only this container. If you are filtering container servers in a WebSphere Application Server Network Deployment environment...

    <cell_name>/<node_name>/<serverName_containerSuffix>

Use with the following arguments: -mapsizes, -teardown,-revisions,-getTraceSpec,-setTraceSpec,-getStatsSpec,-setStatsSpec

-fh n/a Filters for only this host.

Use with the following arguments: -mapsizes, -teardown,-revisions,-getTraceSpec,-setTraceSpec,-getStatsSpec,-setStatsSpec,-routetable

-fm n/a Filters only for this map.

Use with the following arguments: -clear, -mapsizes

-fnp n/a Filters servers that have no primary shards.

Use with the following arguments: -containers

-fp n/a Filters for only this partition.

Use with the following arguments: -mapsizes, -teardown,-revisions,-getTraceSpec,-setTraceSpec,-getStatsSpec,-setStatsSpec,-routetable

-fs n/a Filters for only this server.

If you are filtering application servers in a WebSphere Application Server Network Deployment environment...

    <cell_name>/<node_name>/<server_name>

Use with the following arguments: -mapsizes, -teardown,-revisions,-getTraceSpec,-setTraceSpec,-getStatsSpec,-setStatsSpec

-fst n/a Filters for only this shard type. Specify P for primary shards only, A for asynchronous replica shards only, and S for synchronous replica shards only.

Use with the following arguments: -mapsizes, -teardown,-revisions,-getTraceSpec,-setTraceSpec,-getStatsSpec,-setStatsSpec

-fz n/a Filters for only this zone.

Use with the following arguments: -mapsizes, -teardown,-revisions,-getTraceSpec,-setTraceSpec,-getStatsSpec,-setStatsSpec,-routetable

-force n/a Forces the action that is in the command, disabling any preemptive prompts. This argument is useful for running batched commands.
-g n/a ObjectGrid name.
-getstatsspec n/a Current statistics specification. You can set the statistics specification with the -setstatsspec argument.

Allows the following filters: -fst -fc -fz -fs -fh -fp

-getTraceSpec n/a Current trace specification. You can set the trace specification with the -settracespec argument.

Allows the following filters: -fst -fc -fz -fs -fh -fp

-h n/a Display the help for xsadmin.sh, which includes a list of arguments.
-hosts n/a Display all of the hosts in the configuration.
-jmxUrl XSADMIN_JMX_URL Address of a JMX API connector server in the following format: service:jmx:protocol:sap. The protocol and sap variable definitions follow:

protocol

Transport protocol to be used to connect to the connector server.

sap

Address at which the connector server is found.
For more information about the format of the JMX service URL, see Class JMXServiceURL (Java 2 Platform SE 5.0).
-l n/a Display all known data grids and map sets .
-m n/a Name of the map set.
-mapsizes n/a Display the size of each map on the catalog server to verify that key distribution is uniform over the shards.

Allows the following filters: -fm -fst -fc -fz -fs -fh -fp

-mbeanservers n/a Display a list of all MBean server end points.
-overridequorum n/a

Overrides the quorum setting so that container server events are not ignored during a data center failure scenario.

-password XSADMIN_PASSWORD Password to log in to xsadmin.sh. Do not specify the password in your properties file if you want your password to remain secure.
-p n/a

Indicates the JMX port for the catalog server host.

Default: 1099 or 9809 for a WebSphere Application Server host, 1099 for stand-alone configurations.

-placementStatus

n/a Configured placement and runtime placement of the configuration. You can scope the output to a combination of data grids and map sets , or for the entire configuration:

  • Entire configuration:

      -placementStatus

  • For a specific data grid:

      -placementStatus -g my_grid

  • For a specific map set:

      -placementStatus -m my_mapset

  • For a specific data grid and map set:

      -placementStatus -g my_grid -m my_mapset

-primaries n/a Display a list of the primary shards.
-profile n/a Specifies a fully qualified path to the properties file for xsadmin.sh.
-quorumstatus n/a

Display the status of quorum for the catalog service .

-releaseShard <container_server_name> <objectgrid_name> <map_set_name> <partition_name> n/a Used in conjunction with the -reserveShard argument. The -releaseShard argument must be invoked after a shard has been reserved and placed. . The -releaseShard argument invokes the ContainerMBean.release() method.
-reserved n/a Used with the -containers argument to display only shards that have been reserved with the -reserveShard argument.
-reserveShard <container_server_name> <objectgrid_name> <map_set_name> <partition_name> n/a Moves a primary shard to the specified container server. The ContainerMBean.reserve() method is invoked by this argument.

-resumeBalancing <objectgrid_name> <map_set_name>

n/a Attempts to balance requests. Enables future rebalancing attempts on the specified ObjectGrid and map set.
-revisions n/a Display revision identifiers for a catalog service domain including: each data grid, partition number, partition type (primary or replica), catalog service domain, lifetime ID, and number of data revisions for each specific shard. Use this argument to determine if an asynchronous replica or linked domain is caught up. This argument invokes the ObjectGridMBean.getKnownRevisions() method.

Allows the following filters: -fst -fc -fz -fs -fh -fp

-routetable n/a Display the current state of the data grid from a client server perspective. The route table is the information that an ObjectGrid client server uses to communicate with the data grid. Use the route table as a diagnostic aid when you are trying to identify connection problems or TargetNotAvailable exceptions.

Required arguments: In a stand-alone environment, specify the -bp and -p parameters with this argument if you are not using the default values for the bootstrap listener port and JMX port for the catalog server host.

Allows the following filters: -fz -fh -fp

-settracespec <trace_string> n/a

Enables trace on servers during run time. See the following example:

-setTraceSpec "ObjectGridReplication=all=enabled"

Allows the following filters: -fst -fc -fz -fs -fh -fp

-swapShardWithPrimary <container_server_name> <objectgrid_name> <map_set_name> <partition_name>

n/a Swaps the specified replica shard from the specified container server with the primary shard . By running this command, you can manually balance primary shards when needed.
-setstatsspec <stats_spec> n/a Enables statistics gathering. This argument invokes the DynamicServerMBean.setStatsSpec and DynamicServerMBean.getStatsSpec methods.

Allows the following filters: -fm -fst -fc -fz -fs -fh -fp

-suspendBalancing <objectgrid_name> <map_set_name>

n/a Prevents future attempts to balance the specified ObjectGrid and map set.
-ssl n/a Indicates that SSL is enabled.
-teardown n/a

Stops a list or group of catalog and container servers .

Allows the following filters: -fst -fc -fz -fs -fh -fp

Format to provide a list of servers:

server_name_1,server_name_2 ...

Stop all servers in a zone, include the -fz argument:

    -fz <zone_name>

Stop all servers on a host, include the -fh argument:

    -fh <host_name>
-triggerPlacement n/a Forces shard placement to run, ignoring the configured numInitialContainers value in the deployment XML file. Use this argument when you are performing maintenance on your servers to allow shard placement to continue running, even though the numInitialContainers value is lower than the configured value.
-trustPass XSADMIN_TRUST_PASS Password for the specified truststore.
-trustPath XSADMIN_TRUST_PATH Path to the truststore file. Example: etc/test/security/server.public
-trustType XSADMIN_TRUST_TYPE Type of truststore.

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

-unassigned n/a List of shards that cannot be placed on the data grid. Shards cannot be placed when the placement service has a constraint that is preventing placement.
-username XSADMIN_USERNAME User name to log in to xsadmin.sh.
-v n/a Enables the verbose command-line action. Use this flag if you are using environment variables, a properties file, or both to specify certain command-line arguments, and want to view their values.
-xml n/a Prints the unfiltered output from the PlacementServiceMBean.listObjectGridPlacement() method. The other xsadmin arguments filter the output of this method and organize the data into a more consumable format.

developerWorks: Enhancing xsadmin for WebSphere eXtreme Scale

developerWorks: Enhancing xsadmin for WebSphere eXtreme Scale


Verbose option for xsadmin.sh

Use the xsadmin verbose option to troubleshoot problems. Run the xsadmin -v command to list all configured parameters. The verbose option displays all values in all scopes, including command line arguments, properties file arguments, and environment-specified arguments. The Effective arguments section includes the settings that are being used in the environment if you have specified the same property using multiple scopes.


Verbose option example

xsadmin command arguments:

The following text is an example of output when using the verbose option from the command line after you run the following command with a properties value specified:

-/xsadmin -l  \
          -v  \
          -username xsadmin  \
          -password xsadmin  \
          -ssl  \
          -trustPass ogpass  \
          -profile /opt/ibm/WebSphere/wxs71/ObjectGrid/security/my.properties

The contents of the /opt/ibm/WebSphere/wxs71/ObjectGrid/security/my.properties properties file follow:

XSADMIN_TRUST_PASS=ogpass
XSADMIN_TRUST_TYPE=jks
XSADMIN_TRUST_PATH=/opt/ibm/WebSphere/wxs71/ObjectGrid/bin/security/key.jks
XSADMIN_USERNAME=ogadmin
XSADMIN_PASSWORD=ogpass

Command results: In the following output from the preceding xsadmin command, the text that is in bold italics indicates properties and values specified both on the command line and in the properties file. In the Effective command line arguments section, you can see that the command line specified arguments override the values in the properties file.

Command line specified arguments
**********************************
XSADMIN_USERNAME=xsadmin
XSADMIN_PASSWORD=xsadmin
XSADMIN_TRUST_PATH=<unspecified>
XSADMIN_TRUST_TYPE=<unspecified>
XSADMIN_TRUST_PASS=ogpass
XSADMIN_PROFILE=/opt/ibm/WebSphere/wxs71/ObjectGrid/security/my.properties
XSADMIN_JMX_URL=<unspecified>
**********************************
Properties file specified arguments
************************************
XSADMIN_USERNAME=ogadmin
XSADMIN_PASSWORD=ogpass
XSADMIN_TRUST_PATH=/opt/ibm/WebSphere/wxs71/ObjectGrid/bin/security/key.jks
XSADMIN_TRUST_TYPE=jks
XSADMIN_TRUST_PASS=ogproppass
XSADMIN_JMX_URL=<unspecified>
**********************************
Environment-specified arguments
**********************************
XSADMIN_USERNAME=<unspecified>
XSADMIN_PASSWORD=<unspecified>
XSADMIN_TRUST_PATH=<unspecified>
XSADMIN_TRUST_TYPE=<unspecified>
XSADMIN_TRUST_PASS=<unspecified>
XSADMIN_JMX_URL=<unspecified>
**********************************
Effective arguments
**********************************
XSADMIN_USERNAME=xsadmin
XSADMIN_PASSWORD=xsadmin
XSADMIN_TRUST_PATH=/opt/ibm/WebSphere/wxs71/ObjectGrid/bin/security/key.jks
XSADMIN_TRUST_TYPE=jks
XSADMIN_TRUST_PASS=ogpass
XSADMIN_PROFILE=/opt/ibm/WebSphere/wxs71/ObjectGrid/security/my.properties
XSADMIN_JMX_URL=<unspecified>
SSL authentication enabled: true
**********************************
Connecting to Catalog service  at localhost:1099
*** Show all 'objectGrid:mapset' names 
Grid Name  MapSet Name   
accounting defaultMapSet 

The XSADMIN_PROFILE property, although it displays in the verbose output, is not a valid key that you can specify in a properties file. The value of this property in the verbose output indicates the property value that is being used, as indicated in the -profile command line argument.


Output without the verbose option

An example of the same command output without the verbose option enabled follows:

> ./xsadmin -l 
          -username xsadmin 
          -password xsadmin 
          -ssl 
          -trustPass ogpass 
          -profile /opt/ibm/WebSphere/wxs71/ObjectGrid/security/my.properties


Connecting to Catalog service  at localhost:1099
*** Show all 'objectGrid:mapset' names 
Grid Name  MapSet Name   
accounting defaultMapSet