Administering with the xscmd utility

With the xscmd utility, you can complete administrative tasks in the environment such as: establishing multi-master replication links, overriding quorum, and stopping groups of servers with the teardown command.

Before you begin

  • Your catalog servers and container servers must be started. If your catalog servers are in a catalog service domain, at least two catalog servers must be started.
  • Verify that the JAVA_HOME environment variable is set to use the runtime environment that installed with the product. If you are using the trial version of the product, you must set the JAVA_HOME environment variable.

About this task

The xscmd utility replaces the xsadmin sample utility as a fully supported monitoring and administration tool. You could complete similar operations with the xsadmin tool, but this tool is not supported. The xsadmin sample provides a method for parsing and discovering current deployment data, and can be used as a foundation for writing custom utilities. If you were previously using the xsadmin tool for monitoring and administration, consider updating your scripts to use the xscmd utility. For information about mapping xsadmin commands to the new xscmd commands, see xsadmin tool to xscmd tool migration.

Procedure

  1. Optional: If client authentication is enabled: Open a command-line window. On the command line, set appropriate environment variables.
  2. Go to the wxs_home/bin directory.

    cd wxs_home/bin

  3. Display help for the various xscmd options.
    • To display the general help, run the following command:
      • [Unix]./xscmd.sh -h
      • [Windows]xscmd.bat -h
    • To display a list of all of the commands, run the following command:
      • [Unix]./xscmd.sh -lc
      • [Windows]xscmd.bat -lc
    • To display the help for a specific command, run the following command:
      • [Unix]./xscmd.sh -h command_name
      • [Windows]xscmd.bat -h command_name
    • To display a list of the command groups, run the following command:
      • [Unix]./xscmd.sh -lcg
      • [Windows]xscmd.bat -lcg
    • To display a list of the commands within a command group, run the following command:
      • [Unix]./xscmd.sh -lc command_group_name
      • [Windows]xscmd.bat -lc command_group_name
  4. Run commands that connect to specific catalog servers.
    By default, xscmd connects to the catalog server on the local host, using the host name and port of localhost:2809. You can also provide a list of host names and ports to the command so that you can connect to catalog servers on other hosts. From the list, the xscmd utility connects to a random host. The list of hosts that you provide must be within the same catalog service domain.When you use the appliance command-line interface, you can connect to the local collective only. To connect to remote collectives, you can use a client installation or use the appliance command-line interface on one of the appliances in the remote collective.
    • Provide a list of stand-alone catalog servers to connect:
      • [Unix]./xscmd.sh -c <command_name> -cep hostname:port(,hostname:port)
      • [Windows]xscmd.bat -c <command_name> -cep hostname:port(,hostname:port)
      In the previous commands, command_name is the name of the command that you are running. The hostname:port value is the catalog server host name and listener port. The listener port value on a stand-alone catalog server is specified when you run the startOgServer [Version 8.6 and later] or startXsServer command.
    • Provide a list of WebSphere® Application Server catalog servers to connect. You cannot connect to catalog servers that are running on WebSphere Application Server with the default localhost value:
      • [Unix]./xscmd.sh -c <command_name> -cep was_hostname:port(,hostname:port)
      • [Windows]xscmd.bat -c <command_name> -cep was_hostname:port(,hostname:port)
      In the previous commands, command_name is the name of the command that you are running. The was_hostname value is the host name of the catalog server in the WebSphere Application Server cell. The port value is the listener port.
      [Version 8.6 and later]The listener port value in WebSphere Application Server is inherited:
      • If you are using the ORB transport, the BOOTSTRAP_ADDRESS value for each WebSphere Application Server application server is used. The default value is 9809 if the catalog server is running on the deployment manager.
      • If you are using the IBM eXtremeIO transport, the XIO_ADDRESS value is used. The default value is 4809 if the catalog server is running on the deployment manager.
      If you are running the catalog server on an application server, check the BOOTSTRAP_ADDRESS or XIO_ADDRESS port configuration of the application server to determine the port number.
      Important: If your container servers are running in a secured WebSphere Application Server environment, run the xscmd utility from the WebSphere eXtreme Scale Client installation in the WebSphere Application Server environment. For example, from the /opt/IBM/WebSphere/AppServer/bin directory.
  5. Optional: [Version 8.6 and later]Set a timeout value when you run your commands.
    You can use the -to or --timeout option as a global parameter on any command. This value specifies the number of seconds before timing out when you are connecting to catalog servers in your command. 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 timeout value is set to 30 seconds.

  6. Optional: [Version 8.6 and later] Set JVM arguments when you run your commands.
    In Liberty environments, use the jvm.options to run xscmd with additional JVM arguments. In other environments, JVM arguments can be added using the -jvmArgs option. Add the -jvmArgs to the end of the xscmd command. For example: xscmd.sh -c showplacement -jvmArgs -Xmx256m -XX:MaxPermSize=2048m