Catalog service domain administrative tasks
You can use the Jacl or Jython scripting languages to manage catalog service domains in your WebSphere® Application Server configuration.
Requirements
You must have the WebSphere eXtreme Scale Client installed in your WebSphere Application Server environment.List all administrative tasks
To get a list of all of the administrative tasks that are associated with catalog service domains, run the following command with wsadmin:- Using Jacl:
wsadmin>$AdminTask help XSDomainManagement
- Using a Jython
string:
wsadmin>print AdminTask.help ('XSDomainManagement')
Commands
The administrative tasks for catalog service domains include the following commands:List all administrative task command arguments
To get a list of all of the command arguments associated with catalog service domain administrative tasks, run the following command with wsadmin:- Using
Jacl:
wsadmin>$AdminTask help <command> wsadmin>$AdminTask help <command> <commandStep> Example: wsadmin>$AdminTask help createXSDomain defineDomainServers
- Using a Jython
string:
wsadmin>print AdminTask.help ('<command>') Example: wsadmin>print AdminTask.help ('createXSDomain')
createXSDomain
The createXSDomain command registers a new catalog service domain.Argument | Description |
---|---|
-name (required) | Specifies the name of the catalog service domain that you want to create. |
-default | Specifies whether the catalog service domain is the default for the cell. The default value is true. (Boolean: set to true or false) |
-enableXIO |
Specifies whether IBM eXtreme IO (XIO) or the Object Request Broker (ORB) is
used for transport communication in this catalog service domain.
|
-properties | Specifies custom properties for the catalog service domain. |
Argument | Description |
---|---|
name_of_endpoint | Specifies the name of the catalog service domain endpoint.
|
custom_properties | Specifies custom properties for the catalog service domain endpoint. If you do not have any custom properties, use a set of double quotation marks ("") for this argument. |
endpoint_ports |
Specifies the port numbers for the catalog service domain endpoint. The ports must be specified in the following order: <client_port>,<listener_port> For existing application servers where only a client port is required, enter the client port
value as either "2809" or "2809,". For remote servers
where only a listener port is required, enter the listener port value as:
”,9810”
|
Argument | Description |
---|---|
-securityEnabled | Specifies that client security is enabled for the catalog server. The server properties file that is associated with the selected catalog server must have a matching securityEnabled setting in the server properties file. If these settings do not match, an exception results. (Boolean: set to true or false) |
-credentialAuthentication (optional) | Indicates if credential authentication is enforced or supported.
|
-authenticationRetryCount (optional) | Specifies the number of times that authentication gets tried again if the
credential is expired. If you do not want to try authentication again, set the value to 0. The default value is 0. |
-credentialGeneratorClass | Indicates the com.ibm.websphere.objectgrid.security.plugins.builtins. WSTokenCredentialGenerator implementation class, so the client retrieves the security tokens from the thread. |
-credentialGeneratorProps | Specifies the properties for the CredentialGenerator
implementation class. The properties are sent to the object with the
setProperties(String) method. The credential generator properties value is used
only when a value is specified for the Credential generator class field.
Properties for
includes userid_password which can be defined as “userid
password”. Note: Because parsing of the userid_password property depends
upon the space character as the value separator, userids and passwords which contain spaces must use
the “\20” escape character to represent a space. For example: If the userid
is “Test User Id” and the password is “Test Password”,
the userid_password property should be entered as: “Test\20User\20Id
Test\20Password”.
Properties for
includes the property subject_type, which can be defined as
either“runAs” or “caller”. |
Return value:
Batch mode example 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>.
- Create a catalog service domain of remote endpoints using
Jacl:
$AdminTask createXSDomain {-name TestDomain -default true -defineDomainServers {{xhost1.ibm.com "" ,2809}} -configureClientSecurity {-securityEnabled false -credentialAuthentication Required -authenticationRetryCount 0 -credentialGeneratorClass com.ibm.websphere.objectgrid.security.plugins.builtins.UserPasswordCredentialGenerator -credentialGeneratorProps "manager manager1"}}
- Create a catalog service domain of remote endpoints using Jython
string:
AdminTask.createXSDomain('[-name TestDomain -default true -defineDomainServers [[xhost1.ibm.com "" ,2809] [xhost2.ibm.com "" ,2809]] -configureClientSecurity [-securityEnabled false -credentialAuthentication Required -authenticationRetryCount 0 -credentialGeneratorClass com.ibm.websphere.objectgrid.security.plugins.builtins.UserPasswordCredentialGenerator -credentialGeneratorProps "manager manager1"] ]')
- Create a catalog service domain of existing application server endpoints using
Jacl:
$AdminTask createXSDomain {-name TestDomain -default true -defineDomainServers {{cellName/nodeName/serverName "" 1109}}}
- Using Jacl:
$AdminTask createXSDomain {-interactive}
- Using Jython string:
AdminTask.createXSDomain ('[-interactive]')
deleteXSDomain
The deleteXSDomain command deletes a catalog service domain.
- -name
- Specifies the name of the catalog service domain to delete.
Return value:
- Using Jacl:
$AdminTask deleteXSDomain {-name TestDomain }
- Using Jython string:
AdminTask.deleteXSDomain('[-name TestDomain ]')
- Using Jacl:
$AdminTask deleteXSDomain {-interactive}
- Using Jython string:
AdminTask.deleteXSDomain ('[-interactive]')
getDefaultXSDomain
The getDefaultXSDomain command returns the default catalog service domain for the cell.
Required parameters: None
Return value: The name of the default catalog service domain.
- Using Jacl:
$AdminTask getDefaultXSDomain
- Using Jython string:
AdminTask.getDefaultXSDomain
- Using Jacl:
$AdminTask getDefaultXSDomain {-interactive}
- Using Jython string:
AdminTask.getDefaultXSDomain ('[-interactive]')
listXSDomains
The listXSDomains command returns 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.
- Using Jacl:
$AdminTask listXSDomains
- Using Jython string:
AdminTask.listXSDomains
- Using Jacl:
$AdminTask listXSDomains {-interactive}
- Using Jython string:
AdminTask.listXSDomains ('[-interactive]')
modifyXSDomain
The modifyXSDomain command modifies 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: <client_port>,<listener_port>.
Argument | Description |
---|---|
-name (required) | Specifies the name of the catalog service domain that you want to edit. |
-default | If set to true, specifies that the selected catalog service domain is the default for the cell. (Boolean) |
-enableXIO |
Specifies whether IBM eXtreme IO (XIO) or the Object Request Broker (ORB) is
used for transport communication in this catalog service domain.
|
-properties | Specifies custom properties for the catalog service domain. |
Argument | Description |
---|---|
name_of_endpoint | Specifies the name of the catalog service domain endpoint.
|
endpoint_ports |
Specifies the port numbers for the catalog service domain endpoint. The endpoints must be specified in the following order: <client_port>,<listener_port> For existing application servers where only a client port is required, enter the client port
value as either: ”2809” or “2809,”. For remote servers
where only a listener port is required, enter the listener port value as:
”,9810”.
|
Argument | Description |
---|---|
name_of_endpoint | Specifies the name of the catalog service domain endpoint.
|
custom_properties | Specifies custom properties for the catalog service domain endpoint. If you do not have any custom properties, use a set of double quotation marks ("") for this argument. |
endpoint_ports |
Specifies the port numbers for the catalog service domain endpoint. The endpoints must be specified in the following order: <client_port>,<listener_port> For existing application servers where only a client port is required, enter the client port
value as either: ”2809” or “2809,”. For remote servers
where only a listener port is required, enter the listener port value as :
”,9810”.
|
Argument | Description |
---|---|
name_of_endpoint | Specifies the name of the catalog service endpoint to delete. |
Argument | Description |
---|---|
-securityEnabled | Specifies that client security is enabled for the catalog server. The server properties file that is associated with the selected catalog server must have a matching securityEnabled setting in the server properties file. If these settings do not match, an exception results. (Boolean: set to true or false) |
-credentialAuthentication (optional) | Indicates whether credential authentication is enforced or supported.
|
-authenticationRetryCount (optional) | Specifies the number of times that authentication gets tried again if the
credential is expired. If you do not want to try authentication again, set the value to 0. The default value is 0. |
-credentialGeneratorClass | Indicates the com.ibm.websphere.objectgrid.security.plugins.builtins. WSTokenCredentialGenerator implementation class, so the client retrieves the security tokens from the thread. |
-credentialGeneratorProps | Specifies the properties for the CredentialGenerator
implementation class. The properties are sent to the object with the
setProperties(String) method. The credential generator properties value is used
only when a value is specified for the Credential generator class field.
Properties for
includes userid_password which can be defined as “userid
password”. Note: Because parsing of the userid_password property depends
upon the space character as the value separator, userids and passwords which contain spaces must use
the “\20” escape character to represent a space. For example: If the userid
is “Test User Id” and the password is “Test Password”,
the userid_password property should be entered as: “Test\20User\20Id
Test\20Password”.
Properties for
includes the property subject_type, which can be defined as
either“runAs” or “caller”. |
Return value:
- Using
Jacl:
$AdminTask modifyXSDomain {-name TestDomain -default true -modifyEndpoints {{xhost1.ibm.com "" ,2809}} -addEndpoints {{xhost2.ibm.com "" ,2809}}} -removeEndpoints {{xhost3.ibm.com}}}
- Using Jython
string:
AdminTask.modifyXSDomain('[-name TestDomain -default false -modifyEndpoints [[xhost1.ibm.com "" ,2809]] -addEndpoints [[xhost3.ibm.com "" ,2809]] -removeEndpoints [[xhost2.ibm.com]]]')
- Using the client security specification during the modify command:
$AdminTask modifyXSDomain {-name myDomain -default false -configureClientSecurity {-securityEnabled true - Supported -authenticationRetryCount 1 -credentialGeneratorClass com.ibm.websphere.objectgrid.security.plugins.builtins.UserPasswordCredentialGenerator -credentialGeneratorProps "manager manager1"}}
- Modify an existing catalog service domain to turn on IBM eXtremeIO:
AdminTask.modifyXSDomain('[-name testDomain -enableXIO true]')
- Using Jacl:
$AdminTask modifyXSDomain {-interactive}
- Using Jython string:
AdminTask.modifyXSDomain ('[-interactive]')
getTransport
The getTransport command displays the transport type for the catalog service domain or the existing catalog server. The transport type will be either IBM eXtremeIO (XIO) or Object Request Broker (ORB). If you run this command on a catalog service domain that contains remote servers, or if the catalogServerName is a remote server, an error results. You must use the xscmd -c showTransport command for remote servers.
- -domainName
- Specifies the name of the catalog service domain for which to display the transport type.
- -catalogServerName
- Specifies the name of the catalog server for which to display the transport type.
Return value: ORB or XIO
- Using Jacl:
$AdminTask getTransport {-domainName TestDomain }
- Using Jython
string:
AdminTask.getTransport('[-domainName testDomain]')
- Using
Jacl:
$AdminTask getTransport {-catalogServerName myCell01\myNode01\container1 }
- Using Jython
string:
AdminTask.getTransport('[-catalogServerName myCell01\myNode01\container1]')
- Using Jacl:
$AdminTask getTransport {-interactive}
- Using Jython string:
AdminTask.getTransport ('[-interactive]')
testXSDomainConnection
The testXSDomainConnection command tests the connection to a catalog service domain.
- -name
- Specifies the name of the catalog service domain to which to test the connection.
- -timeout
- Specifies the maximum amount of time to wait for the connection, in seconds.
Return value: If a connection can be made, returns started, otherwise, returns stopped.
- Using Jacl:
$Admintask testXSDomainConnection
- Using Jython string:
AdminTask.testXSDomainConnection
- Using Jacl:
$AdminTask testXSDomainConnection {-interactive}
- Using Jython
string:
AdminTask.testXSDomainConnection ('[-interactive]')
testXSServerConnection
The testXSServerConnection command tests 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.
- host
- Specifies the host on which the catalog server resides.
- listenerPort
- Specifies the listener port for the catalog server.
- timeout
- Specifies the maximum amount of time to wait for a connection to the catalog server, in seconds.
- domain
- Specifies the name of a catalog service domain. If you define a value for this parameter, the client security properties for the specified catalog service domain are used to test the connection. Otherwise, a search occurs to find the catalog service domain for the specified host and listener port. If a catalog service domain is found, the client security properties that are defined for the catalog service domain are used to test the server. Otherwise, no client security properties are used during the test.
Return value: If a connection can be made, returns started, otherwise returns stopped.
- Using
Jacl:
$Admintask testXSServerConnection {-host xhost1.ibm.com -listenerPort 2809}
- Using Jython
string:
AdminTask.testXSServerConnection('[-host xshost3.ibm.com -listenerPort 2809]')
- Using Jacl:
$AdminTask testXSServerConnection {-interactive}
- Using Jython
string:
AdminTask.testXSServerConnection ('[-interactive]')