Administering with the xscmd utility

With the xscmd utility, you can complete administrative tasks in the environment.

Before you begin

About this task

[Version 2.5 and later] You can run the xscmd utility from a client installation or from the appliance command-line interface. When you run the xscmd utility from the appliance command-line interface, it automatically connects to a catalog server in the collective. Setting environment variables and importing the truststore is not required when you run the xscmd utility from the appliance command-line interface. 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.

Procedure

  1. If you are running the xscmd utility from a client installation: Download the active truststore for the appliance to the client. From the appliance user interface, click Collective > Settings > Transport Layer Security > Download active truststore. The default truststore file is the xsatruststore.jks file. The default password for this file is: xc10pass.
  2. Optional: If client authentication is enabled: On the client installation, open a command-line window. On the command line, set appropriate environment variables.
  3. Connect the xscmd utility to the appliance.
    • If you are running the xscmd utility from a client installation:
      From the bin directory in the client installation, run the following command:
      xscmd.bat|sh -ts xsatruststore.jks -tst jks -tsp xc10pass -user xcadmin -pwd xcadmin 
      -cep myxc10.mycompany.com  -prot TLS -cxpv IBMJSSE2 -tt TCP/IP [additional parameters]
    • [Version 2.5 and later] If you are running the xscmd utility from the appliance command-line interface:
      1. Connect to the command-line interface. For more information, see Using the command line interface to run operations on your appliance.
      2. Run the xscmd utility:
        The general syntax of the command follows:
        Console> xscmd -c <command_name> -opt1 [arg1] -opt2 [arg2] -opt3
        The following command displays the help for the appliance:
        Console> xscmd -h
  4. Display help for the various xscmd options. If you are running the xscmd utility from the appliance command-line interface, the .bat|.sh extension is not required.
    • 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
  5. Run commands that connect to specific catalog servers. You must provide one or more catalog server IP address and port combinations to retrieve information about the data grids that are running on the appliance.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 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.
    CAUTION:
    Do not use the following commands in a WebSphere® DataPower® XC10 Appliance environment:
    • -c releaseShard
    • -c reserveShard
    • -c swapShardWithPrimary
    • -c suspendBalancing
    • -c resumeBalancing
    • -c teardown
    • -c triggerPlacement
    • -c enableForPlacement
  6. Optional: 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.