Jazz for Service Management Version 1.1 FIx Pack 3 Beta. Configuration Guide Draft

Transcription

1 Jazz for Serice Management Version 1.1 FIx Pack 3 Beta Configuration Guide Draft

2

3 Jazz for Serice Management Version 1.1 FIx Pack 3 Beta Configuration Guide Draft

4 Note Before using this information and the offering it supports, read the information in Notices on page 329. This edition applies to Version 1.1 FP 3 Beta of Jazz for Serice Management and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright IBM Corporation 2012, US Goernment Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

5 Contents Figures Tables ii Chapter 1. Configuring Jazz for Serice Management How do I configure Jazz for Serice Management.. 1 LDAP user registry requirement Federated repository configuration requirement.. 3 SSO in Jazz for Serice Management Clock synchronization requirement Global security configuration requirement... 4 Chapter 2. Configuring Jazz for Serice Management for a central user registry. 7 Adding the LDAP user registry as a federated repository Configuring the LDAP federated repository Managing LDAP users in the console Adding users by using the WebSphere administratie console Managing roles for users Configuring an SSL connection to an LDAP serer 13 Configuring Cognos-based Tioli Common Reporting engine with LDAP Configuring Cognos-based Tioli Common Reporting engine with Actie Directory Chapter 3. Configuring Jazz for Serice Management for SSO Configuring SSO on the application serer Importing LTPA keys Generating LTPA keys Exporting LTPA keys Configuring the LTPA token timeout alue on the application serer Chapter 4. Configuring Administration Serices Administration Serices roles Administration Serices client Configuring the Administration Serices client. 25 Administration Serices properties Administration Serices command-line interface 27 Administration serice proider Registering the administration serice proider 35 Unregistering the administration serice proider 36 Managed resources of the administration serice proider Registering resources interactiely Registering resources silently Adding custom serice types Resource registration response file Rehosting the Registry Serices Tasks and task bundles Task bundles Tasks Deploying task bundles from the command line 42 Updating tasks from the command line Deleting tasks from the command line Configuring the connection to the Registry Serices application Administration Serices UI properties Administration Serices Base Edition Task and task bundle operations Administration Serices Base Edition command-line interface Chapter 5. Configuring the LTPA token timeout alue on the application serer 51 Chapter 6. Configuring Administration Serices Administration Serices roles Administration Serices client Configuring the Administration Serices client. 55 Administration Serices properties Administration Serices command-line interface 57 Administration serice proider Registering the administration serice proider 65 Unregistering the administration serice proider 66 Managed resources of the administration serice proider Registering resources interactiely Registering resources silently Adding custom serice types Resource registration response file Rehosting the Registry Serices Tasks and task bundles Task bundles Tasks Deploying task bundles from the command line 72 Updating tasks from the command line Deleting tasks from the command line Configuring the connection to the Registry Serices application Administration Serices UI properties Administration Serices Base Edition Task and task bundle operations Administration Serices Base Edition command-line interface Chapter 7. Configuring Dashboard Application Serices Hub Load balancing for Dashboard Application Serices Hub Copyright IBM Corp. 2012, 2014 iii

6 Exporting data from a stand-alone serer to prepare for load balancing Setting up a load balanced cluster Joining a node to a load balancing cluster Enabling serer-to-serer trust Verifying a load balancing implementation Preparing the HTTP serer for load balancing.. 92 Importing stand-alone instance data to a cluster 101 Monitoring a load balancing cluster Remoing a node Remoing a remote node Remoing a load balancing cluster Configuring Tioli Access Manager in Dashboard Application Serices Hub Configuring single sign-on using ETai Checking your Tioli Access Manager configuration Configuring the WebSEAL keystore Creating a WebSEAL junction Creating a WebSEAL junction mapping table 113 Testing the WebSEAL junction Configuring single sign off for Tioli Access Manager and Dashboard Application Serices Hub Setting form-based authentication for WebSEAL 115 Configuring access for HTTP and HTTPS Configuring the LTPA token timeout alue Configuring CMS to use a remote database Creating a database for CMS Deleting a data source definition Creating a data source for a remote database 119 Configuring a hostname to be used by CMS Configuring logging for CMS Verifying your CMS configuration Chapter 8. Configuring Registry Serices Creating client certificates Creating chained client certificates Creating self-signed client certificates Creating CA client certificates Exporting client certificates Importing client certificates through web browser Importing client certificates through WebSphere Application Serer Configuring Registry Serices to support HADR mode Best practices for Registry Serices performance 130 Database settings Application serer settings Registration operations Deletion operations Logging in to the reporting interface Configuring Framework Manager connection Content Store setting in Cognos Configuration Configuring database connections Creating a JDBC database connection for dynamic query mode Connecting to a DB2 database in Compatible mode Connecting to an MS SQL database in Compatible mode Connecting to an Oracle database in Compatible mode Configuring distributed installation for load balancing Configuring security permissions Authentication and authorization in Tioli Common Reporting Constraining access to reports Configuring sample audit reports Appendix. Jazz for Serice Management references Common directory locations Restarting Jazz for Serice Management application serers Stopping Jazz for Serice Management application serers Starting Jazz for Serice Management application serers Jazz for Serice Management CLI references Jazz for Serice Management deployment commands Dashboard Application Serices Hub command reference Registry Serices commands Security Serices commands Tioli Common Reporting commands Registry Serices references HTTP request and response references Registry Serices directory structure CLI properties Using wsadmin scripting tool Security Serices references Jython scripts reference Security Serices sample file reference Notices Support information and feedback 331 Index Chapter 9. Configuring Security Serices Chapter 10. Configuring Tioli Common Reporting Getting started with reports i Jazz for Serice Management: Configuration Guide Draft

7 Figures 1. Output from the isessconfigured command Output from the isessconfiguredltpakeys command Output from the showessltpaconfiguration command Copyright IBM Corp. 2012, 2014

8 i Jazz for Serice Management: Configuration Guide Draft

9 Tables 1. Configuration tasks summary Administration Serices roles and administration serice proider operations Administration Serices roles, and administration serice proider and UI operations Resource details iewresources output iewtasks output iewtasksdetails output Filter options Properties in the resource registration response file Task details iewtasks output iewtasksdetails output Administration Serices roles and administration serice proider operations Administration Serices roles, and administration serice proider and UI operations Resource details iewresources output iewtasks output iewtasksdetails output Filter options Properties in the resource registration response file Task details iewtasks output iewtasksdetails output ETai custom properties Determining the Jazz for Serice Management application serer to start Determining the Jazz for Serice Management application serer to start AddUpdatePreferenceProfile command arguments ChartExport command arguments ChartImport command arguments ChartProperties command arguments RestoreChartStore command arguments ExportPagePlugin command arguments ChartExportPlugin command arguments Import command arguments ImportPagePlugin command arguments cmsupdateremoteentries command arguments Supported language codes for Registry Serices CLI output Parameters used in the install CLI SSL parameters used in the install CLI (FIPS mode enabled) Return codes of the install command run Parameters used in the uninstall CLI SSL parameters used in the uninstall CLI (FIPS mode enabled) Return codes of uninstall command run Parameters used in the update CLI SSL parameters used in the update CLI (FIPS mode enabled) Return codes of the update command run Parameters used in the update CLI SSL parameters used in the update CLI (FIPS mode enabled) Return codes of the update command run Parameters used in the update CLI SSL parameters used in the update CLI (FIPS mode enabled) Return codes of the update command run Parameters used in the database update CLI Return codes of the database update command run Parameters used in the rollback CLI Return codes of the rollback command Parameters used in the config CLI Return codes of config command run Parameters used in the resourceanalytics CLI Return codes of resourceanalytics command run Parameters used in the config CLI Return codes of config command run Parameters used in the config CLI for setting the retryafter alue Return codes of config command run Parameters used in the config CLI for setting the operation mode Return codes of config command run Parameters used in the config CLI for setting the transaction isolation property Return codes of config command run Parameters used in the deleteproider CLI Return codes of the deleteproider command run Parameters used in the config CLI for setting the public URL Return codes of config command run Parameters used in the remapurl CLI Return codes of the remapurl command run Parameters used in the recomputereconciledstate CLI Return codes of the recomputereconciledstate command run Parameters used in the createresourceshapes CLI Return codes of the createresourceshapes command run Parameters used in the updateresourceshape CLI Return codes of the updateresourceshape command run Copyright IBM Corp. 2012, 2014 ii

10 81. Parameters used in the deleteresourceshapes CLI Return codes of the deleteresourceshapes command run Parameters used in the stats CLI Return codes of the stats command run Parameters used in the exportcleansingrules CLI Return codes of the exportcleansingrules command run Parameters used in the updatecleansingrules CLI Return codes of the updatecleansingrules command run Parameters used in the managenamespaceprefixes CLI Return codes of the managenamespaceprefixes command Parameters used in the healthcheck CLI Return codes of the healthcheck command run Parameters used in the showversion CLI Return codes of showversion command run LTPA configuration properties LTPA configuration properties Values for the parameters to start the Registry Serices application Values for the parameters to stop the Registry Serices application Values for the parameters to change the log and trace leels Values for the parameters to change Registry Serices data source settings Values for the parameters to change the user role mapping Values for the parameters to set the maximum number of HTTP sessions Values for the parameters to set the maximum number of threads Values for the parameters to configure the memory settings for the Registry Serices application Values for the parameters to import and export SSL certificates Values for the parameters to import and export SSL certificates iii Jazz for Serice Management: Configuration Guide Draft

11 Chapter 1. Configuring Jazz for Serice Management You can configure Jazz for Serice Management and its integration serices through user interface consoles and command-line interfaces. You can also administer and manage application security and single sign-on. How do I configure Jazz for Serice Management Table 1. Configuration tasks summary You can configure a Jazz for Serice Management application serer for features common to all integration serices. You can also configure indiidual integration serices. Consult the summary of configuration tasks. Gaining familiarity with configurations, concepts, and requirements LDAP user registry requirement on page 3 Federated repository configuration requirement on page 3 SSO in Jazz for Serice Management on page 3 Global security configuration requirement on page 4 Configuration tasks summary During installation by Installation Manager, an integration serice is also configured. By default, an integration serice is configured to use basic authentication oer HTTPS. Table 1 summarizes configuration information and typical configuration tasks for all integration serices and for only an indiidual integration serice. Integration serice Cross-serices Task You can configure a central user registry, such as a Lightweight Directory Access Protocol (LDAP) registry, for Jazz for Serice Management user management and authentication. Configure WebSphere Application Serer to use a central federated repository with an LDAP user registry. After configuration, you can add users to the federated repository. For more information, see Chapter 2, Configuring Jazz for Serice Management for a central user registry, on page 7. You can configure the integration serices for single sign-on, so that users can access Jazz for Serice Management applications by logging in only once. For more information, see Chapter 3, Configuring Jazz for Serice Management for SSO, on page 19. During installation, the global security configuration is enabled that applies to the security policy for all administratie functions in each Jazz for Serice Management application serer. The configuration is also used as a default security policy for user applications. Copyright IBM Corp. 2012,

12 Table 1. Configuration tasks summary (continued) Integration serice Task Administration Serices Administration Serices is configured during installation. You can reconfigure the connection to the Registry Serices application. You can manually install task bundles for other integration serices because of installation problems. Dashboard Application Serices Hub For more information, see Chapter 4, Configuring Administration Serices, on page 23. Dashboard Application Serices Hub is configured during installation. For installations of Dashboard Application Serices Hub with large user populations, you can set up a load balancing cluster of console nodes with identical configurations to eenly distribute user sessions. You can choose to configure Dashboard Application Serices Hub to use Tioli Access Manager WebSEAL Version to manage authentication. You can also configure the Context Menu Serice (CMS) to use a remote database, which can be used by products to share information outside of the Dashboard Application Serices Hub enironment. You can modify the Apache ActieMQ polling interals properties to change the frequency of polls that handle data proider eents, which are sent to the web clients. Registry Serices For more information, see Chapter 7, Configuring Dashboard Application Serices Hub, on page 81. Registry Serices is configured during installation. You configure Registry Serices for secure access to all its features. You can also configure Registry Serices to support the HADR mode and configure specific settings to aoid performance issues. You can work with these configuration tasks through either administratie console or command-line interface. Use the Registry Serices CLIs to configure specific Registry Serices settings. For example, you can define a public URL, set the Registry Serices operation mode, customize Resource Shape definitions, and more. Security Serices For more information, see Chapter 8, Configuring Registry Serices, on page 125. Security Serices is configured during installation except for single sign-on with LDAP, which is done by configuring Jazz for Serice Management for SSO. You can update the configuration, for example, applying new ersions of tokens. For more information, see Chapter 9, Configuring Security Serices, on page Jazz for Serice Management: Configuration Guide Draft

13 Table 1. Configuration tasks summary (continued) Integration serice Task Tioli Common Reporting After you install Tioli Common Reporting, prepare your report packages to be able to generate, publish, and edit your reports. You can configure database connection details to a data source other than DB2. You can configure sample audit reports to iew information about user and report actiity. For installations of Tioli Common Reporting with large user populations, you can set up a load balancing cluster of console nodes with identical configurations to eenly distribute user sessions. For more information, see Chapter 10, Configuring Tioli Common Reporting, on page 137. LDAP user registry requirement Information about users and groups reside in a user registry. You can set up an LDAP serer and create an LDAP user registry for Jazz for Serice Management. It uses this registry for user authentication and the retrieal of information about users and groups to perform security-related functions. Federated repository configuration requirement Federated repositories proide you with the ability to access and maintain user data in multiple repositories, and federate that data into a single federated repository. Jazz for Serice Management requires that you configure WebSphere Application Serer to use central federated repositories with an LDAP user registry. Managing the realm in a federated repository configuration SSO in Jazz for Serice Management Single sign-on (SSO) capabilities in Jazz for Serice Management require that each integration serice and each Jazz for Serice Management application serer use Lightweight Third Party Authentication (LTPA) as the authentication mechanism. After you hae configured LTPA, you can generate LTPA keys and synchronize them across multiple application serer domains or cells in the Jazz for Serice Management distributed enironment. When multiple products and user interfaces are integrated together, the transition from one UI to another should appear as seamless as possible. One aspect of this integration inoles single sign-on functionality, which allows a user to naigate among arious products and user interfaces without being required to enter authentication credentials, such as username and password, more than once. LTPA is the default authentication mechanism for WebSphere Application Serer. WebSphere products include SSO functionality based on LTPA technology. When properly configured, this functionality supports naigation among WebSphere-based applications, passing authentication information as LTPA tokens in HTTP cookies. A user is prompted for authentication credentials only once, and any subsequent authentications are automatically handled under the coers by using the LTPA tokens included in the associated Web requests. Chapter 1. Configuring Jazz for Serice Management 3

14 Configuring LTPA and working with keys Clock synchronization requirement Verify that the time, date, and time zone are synchronized among all serers participating in the protected domain. Because single sign-on authentication uses time-sensitie tokens, you must erify that the time, date, and time zone are synchronized. This erification must be done for all serers that are participating in the protected domain, including the WebSphere Application Serer, the Jazz for Serice Management serers, and serers of other systems in your integrated management enironment. If the time difference is too high between serers, the single sign-on token might prematurely expire on some serers and cause authentication or alidation failures. WebSphere Application Serer and authentication serice-based single sign-on tokens are assigned a lifetime of two hours by default. For best results, serers must be synchronized to within 5 minutes to ensure that single sign-on tokens are ealuated consistently. Global security configuration requirement If you create an application serer profile during installation, global security configuration is enabled, which applies to the security policy for all administratie functions in each Jazz for Serice Management application serer. If you use an existing application serer profile during installation, global security configuration must be enabled post installation. The configuration is used as a default security policy for user applications. To enable global security configuration post installation, see Enabling global security configuration. Administratie security configuration specifies whether to enable administratie security for the application serer domain. Administratie security requires users to authenticate before obtaining administratie control of the application serer. Application security configuration specifies whether to enable security for the applications in your enironment. This type of security proides application isolation and requirements for authenticating application users Related information: Global security settings Enabling global security configuration You can change the global security configuration that applies to the security policy for all administratie functions in the Security > Global Security window in the WebSphere administratie console. Procedure 1. Start the WebSphere administratie console; for example, select Start > IBM WebSphere > IBM WebSphere Application Serer > Profiles > JazzSMProfile > Administratie console. 2. Enter the WebSphere administrator user ID and password, and click Log in. 3. Select Security > Global Security. 4. Ensure the following check boxes are selected: 4 Jazz for Serice Management: Configuration Guide Draft

15 Enable administratie security Enable application security 5. Click Apply and then Sae. 6. Restart the Jazz for Serice Management application serer. See Restarting Jazz for Serice Management application serers on page 157. Chapter 1. Configuring Jazz for Serice Management 5

16 6 Jazz for Serice Management: Configuration Guide Draft

17 Chapter 2. Configuring Jazz for Serice Management for a central user registry You can configure a central user registry, such as a Lightweight Directory Access Protocol (LDAP) registry, for user management and authentication. You can then configure WebSphere Application Serer to use the LDAP user registry as a federated repository. About this task Note: When you add a user, you should check that the user ID that you specify does not already exist in any of the user repositories thereby aoid difficulties when the new user attempts to log in. In a network enironment that includes a user registry on an LDAP serer, you can configure Jazz for Serice Management to use it. These functions require a central user registry: Single sign-on, which authenticates users at the central repository during login and wheneer they start another authorized Jazz for Serice Management or Tioli application. Load balancing for Dashboard Application Serices Hub, which requires that each application serer instance in the cluster use the same central user repository. Before configuring a central user registry, be sure that the user registry or registries that you plan to identify are started and can be accessed from the computer where you hae set up the Jazz for Serice Management application serer. For central user repositories, unique IDs are composed of keys and alues separated by a comma (,), that is, key1=alue1,key2=alue2,key3=alue3. For example, uid=my_name,ou=my_ou_alue,dc=ibm,dc=com. Jazz for Serice Management is currently limited to using lower case keys in relation to unique IDs. For example, the following unique IDs do not work: UID=my_name,OU=my_ou_alue,DC=ibm,DC=com uid=my_name,ou=my_ou_alue,dc=ibm,dc=com Attention: If Jazz for Serice Management is configured with multiple central user repositories, you cannot login if one remote user repository becomes inaccessible from Jazz for Serice Management, een if your user ID exists in one of the other repositories. If you need access in this situation, you hae to run WebSphere Application Serer commands to allow access when all repositories are aailable, or the federated repositories will not function properly. For more information, refer to the following links: com.ibm.websphere.nd.multiplatform.doc/ae/rxml_atidmgrrealmconfig.html Procedure 1. Set up an LDAP serer and create an LDAP user registry for Jazz for Serice Management. Ensure that WebSphere Application Serer supports the LDAP user registry as a federated repository, for example, IBM Tioli Directory Serer or Microsoft Actie Directory Serer. Copyright IBM Corp. 2012,

18 2. Add the LDAP user registry as a federated repository to the Jazz for Serice Management application serer. 3. Configure each Jazz for Serice Management application serer to use the LDAP federated repository. 4. Configure the connection to the LDAP serer for secure communications. 5. If you hae installed Tioli Common Reporting, configure the reporting engine to use the LDAP user registry. Configuring Cognos-based Tioli Common Reporting engine with LDAP on page 14 Configuring Cognos-based Tioli Common Reporting engine with Actie Directory on page 15 Adding the LDAP user registry as a federated repository After setting up the LDAP serer, you must add it as a federated repository in the Federated Repositories > Repository references > New window. Procedure 1. Start the WebSphere administratie console; for example, select Start > IBM WebSphere > IBM WebSphere Application Serer > Profiles > JazzSMProfile > Administratie console. 2. Enter the WebSphere administrator user ID and password, and click Log in. 3. Select Security > Global security. 4. From the Aailable realm definitions list, select Federated repositories and click Configure. 5. In the Related Items area, click the Manage repositories link and then click Add repositories to add the LDAP user registry as a federated repository. 6. Click New Repository > LDAP repository. 7. In the Repository identifier field, proide a unique identifier for the repository. The identifier uniquely identifies the repository within the cell, for example, LDAP1. 8. From the Directory type list, select the type of LDAP serer. The type of LDAP serer determines the default filters that are used by WebSphere Application Serer. 9. In the Primary host name field, enter the fully qualified host name of the primary LDAP serer. The primary host name and the distinguished name must contain no spaces. You can enter either the IP address or the domain name system (DNS) name. 10. In the Port field, enter the serer port of the LDAP user registry. The host name and the port number represent the realm for this LDAP serer in a mixed ersion nodes cell. If serers in different cells are communicating with each other using Lightweight Third Party Authentication (LTPA) tokens, these realms must match exactly in all the cells. Note: The default port alue is 389, which is not a Secure Sockets Layer (SSL) connection port. Use port 636 for a Secure Sockets Layer (SSL) connection. For some LDAP serers, you can specify a different port. If you do not know the port to use, contact your LDAP serer administrator. 11. Optional: In the Bind distinguished name and Bind password fields, enter the bind distinguished name (DN) (for example, cn=root) and password. 8 Jazz for Serice Management: Configuration Guide Draft

19 Note: The bind DN is required for write operations or to obtain user and group information if anonymous binds are not possible on the LDAP serer. In most cases, a bind DN and bind password are needed, except when an anonymous bind can satisfy all of the required functions. Therefore, if the LDAP serer is set up to use anonymous binds, leae these fields blank. 12. Optional: In the Login properties field, enter the property names used to log into the WebSphere Application Serer. This field takes multiple login properties, delimited by a semicolon (;). For example, cn. 13. Optional: From the Certificate mapping list, select your preferred certificate map mode. You can use the X.590 certificates for user authentication when LDAP is selected as the repository. Note: The Certificate mapping field is used to indicate whether to map the X.509 certificates into an LDAP directory user by EXACT_DN or CERTIFICATE_FILTER. If you select EXACT_DN, the DN in the certificate must match the user entry in the LDAP serer, including case and spaces. 14. Click Apply and then Sae. 15. Log out of the WebSphere administratie console. Configuring the LDAP federated repository You can configure each Jazz for Serice Management application serer to use and communicate with the LDAP federated repository. About this task In a Jazz for Serice Management distributed enironment or in a Dashboard Application Serices Hub load balanced enironment, all application serer instances must be configured separately for the LDAP serer. Procedure 1. Start the WebSphere administratie console; for example, select Start > IBM WebSphere > IBM WebSphere Application Serer > Profiles > JazzSMProfile > Administratie console. 2. Enter the WebSphere administrator user ID and password, and click Log in. 3. Select Security > Global security. 4. From the Aailable realm definitions list, select Federated repositories and click Configure. 5. To add an entry to the base realm: a. Ensure that the LDAP federated repository is selected from the Repository list. b. In the field, enter the distinguished name (DN) of a base entry that uniquely identifies this set of entries in the realm. This base entry must uniquely identify the external repository in the realm. Note: If multiple repositories are included in the realm, use the DN field to define an additional distinguished name that uniquely identifies this set of entries within the realm. For example, repositories LDAP1 and LDAP2 might both use o=ibm,c=us as the base entry in the repository. So o=ibm,c=us is used for LDAP1 and o=ibm2,c=us for LDAP2. The specified DN in this field maps to the LDAP DN of the base entry within the repository (such as o=ibm,c=us b). The base entry indicates the starting point for searches in this LDAP serer (such as o=ibm,c=us c). Chapter 2. Configuring Jazz for Serice Management for a central user registry 9

20 c. Click Apply and then Sae. 6. In the WebSphereadministratie console, select Security > Global security. 7. From the Aailable realm definitions list, select Federated repositories and click Set as current to mark the federated repository as the current realm. 8. Restart each Jazz for Serice Management application serer. Restarting Jazz for Serice Management application serers on page Verify that the federated repository is correctly configured: a. In the Dashboard Application Serices Hub naigation pane, click Users and Groups > Manage Users. b. Select User ID from the Search by list. c. Click Search to search for users in the federated repository. d. Confirm that the list includes users from both the LDAP federated repository and the local file registry. On the Jazz for Serice Management application serer, LDAP users are queried only by the userid attribute. When users are imported into LDAP federated repository by using an LDAP Data Interchange Format (LDIF) file, an auxiliary class of type eperson and an uid attribute is added to the LDAP user ID. Only perform this task, if you want to search the LDAP federated repository by using VMM from the serer. What to do next You can create or manage users in Dashboard Application Serices Hub that are defined in your LDAP federated repository. In the WebSphere administratie console, you must specify the supported entity types. Managing LDAP users in the console To create or manage users in the console that are defined in your LDAP repository, in the WebSphere Application Serer administratie console specify the supported entity types. About this task To create or manage LDAP users in the console: Procedure 1. Log in to the Dashboard Application Serices Hub. 2. In the naigation pane, click Settings > Websphere Admin Console and click Launch Websphere Admin Console. 3. In the WebSphere Application Serer administratie console, select Security > Global security. 4. From the Aailable realm definitions list, select Federated repositories and click Configure. 5. In the Additional Properties area, click Supported entity types, to iew a list of predefined entity types. 6. Click the name of a predefined entity type to change its configuration. 7. In the Base entry for the default parent field, proide the distinguished name of a base entry in the repository. This entry determines the default location in the repository where entities of this type are placed on write operations by user and group management. 10 Jazz for Serice Management: Configuration Guide Draft

21 8. In the Relatie Distinguished Name properties field, proide the relatie distinguished name (RDN) properties for the specified entity type. Possible alues are cn for Group, uid or cn for PersonAccount, and o, ou, dc, and cn for OrgContainer. Delimit multiple properties for the OrgContainer entity with a semicolon (;). 9. Click OK to return to the Supported entity types page. 10. In the Messages area of the Global security page, click the Sae link and log out of the WebSphere Application Serer console. 11. For the changes to take effect, stop, and restart the Jazz for Serice Management application serer. In a load balanced enironment, you must stop and restart each Jazz for Serice Management application serer instance. 12. Stop and restart the serer. Results You can now manage your LDAP repository users in the console through the Users and Groups > Manage Users menu items. Note: When you add a new user, you should check that the user ID you specify does not already exist in any of the user repositories to aoid difficulties when the new user attempts to log in. Restriction: You cannot currently update user IDs through the Users and Groups > Manage Users page that hae been created in Microsoft Actie Directory repositories. Adding users by using the WebSphere administratie console You can manage your LDAP Federated repository users in the Manage Users > Create a User window in the WebSphere administratie console. You can create users in the user registry with a login account. Before you begin Before you add users, perform the following tasks: Verify that you hae properly configured the LDAP user registry that contains the users that you want to assign. It is preferable to hae security turned on with the user registry of your choice before beginning this process. Ensure that if you change anything in the security configuration that you sae the configuration and restart the application serer before the changes become effectie. For example, enable security or change the user registry. Tip: When you add a user, erify that the user ID that you specify does not already exist in any user registry to aoid login issues for the new user. About this task If you hae installed Dashboard Application Serices Hub, you can configure Jazz for Serice Management application serer to manage LDAP users by using Dashboard Application Serices Hub. See Managing LDAP users in the console on page 10. Chapter 2. Configuring Jazz for Serice Management for a central user registry 11

22 Procedure 1. Start the WebSphere administration console; for example, select Start > IBM WebSphere > IBM WebSphere Application Serer > Profiles > JazzSMProfile > Administratie console. 2. Enter the WebSphere administrator user ID and password, and click Log in. 3. Select Users and Groups > Manage Users. 4. First search for the user to erify whether the user exists in any user registry by using the Search for Users UI controls. 5. If the user does not exist, click Create. 6. Enter the details for the user, such as, the user ID, first and last names, address, password, and any group membership. 7. Click Create. 8. Click Create Like to create another user as outlined in step 6; otherwise, click Close. What to do next After you create the user, map it to the releant Jazz for Serice Management roles, such as PlatformAdministrator, TrustClientRole or chartadministrator. See Assigning users and groups to roles in the WebSphere administratie console or Managing roles for users in Dashboard Application Serices Hub. Managing roles for users Administrators can search for users and manage their roles in the User Roles page. About this task To search for users and manage their roles: Procedure 1. In the naigation pane, click > User Roles. The User Roles page is displayed. 2. In the search fields proided, you can enter search criteria by gien name, surname, user ID, and address. If you do not hae exact details for a particular item, all of the search fields support using an asterisk (*) asa wildcard character. For example, to return all user records with a gien name that starts with Mich, enter mich* in the First name field. Tip: You can leae the search fields blank to return all user records. Tip: To return only users that are currently logged in, leae the search fields blank and select the Actie Users Only check box. 3. From the Number of results to display list, select the number of records that you want returned and click Search. Restriction: Returned records are displayed in one page only. If more records are aailable than the setting you chose from the list, only a partial list is returned. To display all records you need to search again after selecting a larger number from the Number of results to display list. A list of records that match your search criteria are listed in the grid. 12 Jazz for Serice Management: Configuration Guide Draft

23 4. Select a user from the User ID column. A list of aailable roles for the selected user is displayed on a new page. Those roles that are currently associated with the selected user are checked. 5. Modify the roles associated with the user as required, that is, check the roles that you want associated with the user and clear those that you do not. 6. Click Sae to commit your changes, or Reset to reset the form to its initial state. Once you click Sae, the User Roles page is displayed. The entry for the user in the Roles column is updated to reflect your changes. What to do next You can select another user from the search results and update their role settings, enter new search criteria to manage other user records, or close the User Roles page. Configuring an SSL connection to an LDAP serer You can configure secure communications between each Jazz for Serice Management application serer and the LDAP serer by using SSL. Before you begin Ensure that you hae already an existing connection to an LDAP serer set up. Your LDAP serer must be configured to accept SSL connections and be running on the secured port number (636). Refer to your LDAP serer documentation if you need to create a signer certificate, which as part of this task, must be imported from your LDAP serer into the trust store of the Jazz for Serice Managementapplication serer. About this task All Jazz for Serice Managementapplication serers must be configured for the LDAP serer. Procedure 1. Follow these steps to import your LDAP serer's signer certificate into the Jazz for Serice Management application serer trust store. a. Start the WebSphere administratie console; for example, select Start > IBM WebSphere > IBM WebSphere Application Serer > Profiles > JazzSMProfile > Administratie console. b. Enter the WebSphere administrator user ID and password, and click Log in. c. Click Security > SSL certificate and key management. d. In the Related Items area, click the Key stores and certificates link and in the table click the NodeDefaultTrustStore link. e. In the Additional Properties area, click the Signer certificates link and click the Retriee from port button. f. In the releant fields, proide hostname, port (normally 636 for SSL connections), SSL configuration details, as well as the alias of the certificate for your LDAP serer and click the Retriee signer information button and then click OK. 2. Follow these steps to enable SSL communications to your LDAP serer: a. Click Security > Secure administration, applications, and infrastructure. Chapter 2. Configuring Jazz for Serice Management for a central user registry 13

24 b. Select Federated repositories from the Aailable realm definitions drop down list and click Configure. c. Select your LDAP serer from the Repository drop down list. d. Enable the Require SSL communications check box and select the Centrally managed option. e. Click OK. 3. Restart each Jazz for Serice Management application serer. Restarting Jazz for Serice Management application serers on page 157. What to do next If you intend to enable single sign-on (SSO) so that users can log in once and then traerse to other applications without haing to re-authenticate, configure SSO. Configuring Cognos-based Tioli Common Reporting engine with LDAP Use the Cognos Configuration user interface to configure the Cognos-based Tioli Common Reporting engine and use the same user repository as the Tioli Common Reporting application. This procedure is recommended for large user repositories. About this task If you installed your Tioli Common Reporting on a single computer, the Tioli Common Reporting VMMProider is used for LDAP by default, and no additional LDAP configuration is required. Procedure 1. Open the IBM Cognos Configuration by running: Windows Start > All Programs > Tioli Common Reporting 3.1 > IBM Cognos Configuration Linux and UNIX c10_location/bin64/tcr_cogconfig.sh. 2. In the Explorer naigation on the left, go to Security, and right-click the Authentication section. 3. Select New resource > Namespace Type in a name, select the registry type from the expandable list, and click OK. New user registry is added to the list. 5. Select the entry that you created, and edit the fields required for configuration. You must proide different alues depending on the type of user registry selected. For details on how to configure the user registry, see Configuring IBM Cognos Components to Use an Authentication Proider of IBMCognos information center. a. Set Use external identity? to True to enable single sign-on from the console to the reporting engine systems. b. Set External identity mapping to (uid=${enironment("remote_user")}). If you use your address instead of a user ID to log on to the console, set the alue to: (mail=${enironment("remote_user")}). c. Select Enironment in the naigation tree and ensure that host names are set to be fully qualified. 6. Right-click the entry that you created, and select Test to erify it before saing. 14 Jazz for Serice Management: Configuration Guide Draft

25 7. Select Cognos entry, and edit the Allow anonymous access? field, changing it to False. 8. Sae the new configuration. Results Important: When you configure LDAP, the reporting portlet can no longer be used by users that are not contained in the configured LDAP and do not hae the tcrportaloperator role assigned. Configuring Cognos-based Tioli Common Reporting engine with Actie Directory Configure the reporting engine to use the same user repository as the user interface. This procedure is recommended for large user repositories. About this task If you installed Tioli Common Reporting on a single-computer, no additional configuration is required. Howeer, if you chose distributed installation, you must configure Actie Directory on both computers. Important: When you configure the user repository, the reporting portlet can no longer be used by users not contained in the configured user repository. Procedure 1. Open the IBM Cognos Configuration by running: Windows Start > All Programs > Tioli Common Reporting 3.1 > IBM Cognos Configuration Linux and UNIX c10_location/bin64/tcr_cogconfig.sh 2. In the Explorer naigation on the left, go to Security, and right-click the Authentication section. 3. Select New resource > Namespace... Windows If you are using a Windows operating system: a. Enter a name, select Actie Directory as the Type, and click OK. The new user registry is displayed in the Explorer window, under the Authentication component. b. Select the entry that you created, go to the Properties window and in the NamespaceID field, specify a unique identifier for the namespace. Tip: Do not use colons (:) in the Namespace ID property. c. Specify the Host and port. The host and port alues must point to Actie Directory Domain Controller host. d. Specify the Binding credentials. Linux UNIX If you are using a non-windows operating system: a. Enter a name, select LDAP as the Type, and click OK. The new user registry is displayed in the Explorer window, under the Authentication component. b. Select the entry that you created, go to the Properties window and in the NamespaceID field, specify a unique identifier for the namespace. Chapter 2. Configuring Jazz for Serice Management for a central user registry 15

26 Tip: Do not use colons (:) in the Namespace ID property. c. Specify the alues for all other required properties to ensure that IBM Cognos components can locate and use your existing authentication proider. The following settings are examples: For User lookup, specify (samaccountname=${userid}). If you use a single sign-on, set the Use external identity alue to True and specify (samaccountname=${enironment("remote_user")}) for External identity mapping. To remoe the domain name from the REMOTE_USER ariable, specify (samaccountname=${replace(${enironment("remote_user")}, "domain\\","")}). Enter user@domain for Bind user DN and password. Specify objectguid for Unique identifier. d. If you want the LDAP authentication proider to bind to the directory serer using a specific Bind user DN and password when performing searches, then specify these alues. If no alues are specified, the LDAP authentication proider binds as anonymous. e. If you do not use external identity mapping, use bind credentials for searching the LDAP directory serer: Ensure that Use external identity is set to False. Set Use bind credentials for search to True. Specify the user ID and password for Bind user DN and password. f. To configure the LDAP adanced mapping properties for use with the Actie Directory Serer objects, use the alues specified in the list: LDAP properties and LDAP alues for folder mappings: - Object class - organizationalunit, organization, container - Description - description - Name - ou, o, cn LDAP properties and LDAP alues for group mappings: - Object class - group - Description - description - Member - member - Name - cn LDAP properties and LDAP alues for account mappings: - Object class - user - Business phone - telephonenumber - Content locale - Leae this field blank - Description - description - Fax/Phone - facsimiletelephonenumber - Gien name - gienname - Home phone - hometelephonenumber - Mobile phone - mobiletelephonenumber - Password - unicodepassword - Postal address - postaladdress - Product locale - Leae this field blank - Surname - surname 16 Jazz for Serice Management: Configuration Guide Draft

27 - User name - samaccountname These mapping properties represent changes based on a default Actie Directory Serer installation. If you modified the schema, you might need to make additional mapping changes. Note: LDAP attributes that are mapped to the Name property in Folder mappings, Group mappings, and Account mappings must be accessible to all authenticated users. In addition, the Name property must not be blank. g. From the File menu, click Sae. 4. Go to the Explorer window, right-click the new authentication resource under Authentication, and click Test to test the connection to a new namespace. 5. Select the Cognos entry and edit the Allow anonymous access? field changing it to False. Chapter 2. Configuring Jazz for Serice Management for a central user registry 17

28 18 Jazz for Serice Management: Configuration Guide Draft

29 Chapter 3. Configuring Jazz for Serice Management for SSO You can configure the integration serices for single sign-on, so that users can access Jazz for Serice Management applications by logging in only once. About this task Jazz for Serice Management uses LTPA cookies for SSO, such that a cookie is created containing the LTPA token and inserted into the HTTP response when the user logs into the first Jazz for Serice Management application. This LTPA cookie is sent in the request, when the user accesses another Jazz for Serice Management application in the same domain name serice (DNS) domain. If the request is between different WebSphere Application Serer cells, for example, Administration Serices and Registry Serices applications on different computers, you must share the LTPA keys and the federated registry between the cells. In a distributed enironment, all Jazz for Serice Management application serers must be synchronized to share the same LTPA keys. Note: Fix Pack 1 When single sign-on (SSO) is enabled, ensure that you use the fully qualified host name in the URL of the Jazz for Serice Management reporting or UI serers. SSO requires that the browser pass LTPA cookies to the Jazz for Serice Management application serer, and these cookies contain the fully qualified host name. Procedure 1. On each Jazz for Serice Management application serer, configure it for SSO. See Configuring SSO on the application serer. 2. Export the LTPA keys from one of the Jazz for Serice Management application serers. See Exporting LTPA keys on page On the remaining Jazz for Serice Management application serers, import the LTPA keys. See Importing LTPA keys on page Restarting Jazz for Serice Management application serers on page 157 Configuring SSO on the application serer You can enable single sign-on in the Single sign-on (SSO) window in the WebSphere administratie console on each Jazz for Serice Management application serer. About this task You can configure SSO to use LTPA Version 2 tokens and the UseDomainFromURL domain type. Procedure 1. Start the WebSphere administratie console; for example, select Start > IBM WebSphere > IBM WebSphere Application Serer > Profiles > JazzSMProfile > Administratie console. 2. Enter the WebSphere administrator user ID and password, and click Log in. 3. Select Security > Global security. Copyright IBM Corp. 2012,

30 Importing LTPA keys 4. Select Web and SIP Security > Single sign-on (SSO). 5. Select the Enabled check box to enable SSO. 6. Select the Requires SSL check box, if the HTTPS protocol must be used for all requests. 7. In the Domain name, enter UseDomainFromURL to set the domain name to the domain of the host that makes the request. 8. In the LTPA V2 cookie name field, enter the name of the cookie that transmit the LTPA tokens between serers. 9. Select the Web inbound security attribute propagation check box to propagate information from the first login application serer to the other application serers. 10. Click OK and then Sae. You can import LTPA keys from the key file in the LTPA window in the WebSphere administratie console. About this task Generating LTPA keys You must share and import LTPA keys into the remaining WebSphere Application Serer cells, when the cells for the Jazz for Serice Management applications are installed on different computers and you export the keys from one of the cells. Procedure 1. Start the WebSphere administratie console; for example, select Start > IBM WebSphere > IBM WebSphere Application Serer > Profiles > JazzSMProfile > Administratie console. 2. Enter the WebSphere administrator user ID and password, and click Log in. 3. Select Security > Global security. 4. Select LTPA. 5. In the Password and Confirm password fields, enter the password to decrypt the key file. 6. In the Fully qualified key file name field, enter fully qualified path and file name for the key file. 7. Click Import keys. 8. Click OK and then Sae. You can generate LTPA keys in the LTPA window in the WebSphere administratie console. About this task You need to generate only LTPA keys if you do not hae LTPA keys to import from another WebSphere Application Serer. Procedure 1. Start the WebSphere administratie console; for example, select Start > IBM WebSphere > IBM WebSphere Application Serer > Profiles > JazzSMProfile > Administratie console. 20 Jazz for Serice Management: Configuration Guide Draft

31 Exporting LTPA keys 2. Enter the WebSphere administrator user ID and password, and click Log in. 3. Select Security > Global security. 4. Select LTPA. 5. Click Generate keys. 6. Click OK and then Sae. You can export LTPA keys to a key file in the LTPA window in the WebSphere administratie console. About this task You must share and export LTPA keys from a WebSphere Application Serer cell, when the cells for the Jazz for Serice Management applications are installed on different computers and you want to import the keys to the remaining cells. Procedure 1. Start the WebSphere administratie console; for example, select Start > IBM WebSphere > IBM WebSphere Application Serer > Profiles > JazzSMProfile > Administratie console. 2. Enter the WebSphere administrator user ID and password, and click Log in. 3. Select Security > Global Security. 4. Select LTPA. 5. In the Password and Confirm password fields, enter the password to encrypt the key file. 6. In the Fully qualified key file name field, enter fully qualified path and file name for the key file. 7. Click Export keys. 8. Click OK and then Sae. Configuring the LTPA token timeout alue on the application serer You can configure the LTPA token timeout alue for each Jazz for Serice Management application serer in the WebSphereadministratie console. Before you begin Jazz for Serice Management application serer is enabled for single sign-on. About this task The default timeout for an LTPA token is 120 minutes. An LTPA timeout causes you to be logged out from the integration serice application. It can also cause an authentication popup message in Dashboard Application Serices Hub, if the first request after the timeout is an AJAX request from a widget. Note: You can also perform this task by running the Configuration: LTPA Token session TimeOut task from the Administration Serices task bundle for Dashboard Application Serices Hub. Chapter 3. Configuring Jazz for Serice Management for SSO 21

32 Procedure 1. Start the WebSphere administratie console; for example, select Start > IBM WebSphere > IBM WebSphere Application Serer > Profiles > JazzSMProfile > Administratie console. 2. Enter the WebSphere administrator user ID and password, and click Log in. 3. Click Security > Global security. 4. In the Authentication area of the Global security page, click the LTPA link. 5. In the LTPA timeout area of the LTPA page, edit the alue for the LTPA timeout. 6. Click Apply and then Apply. What to do next Remember: Repeat this procedure on each Jazz for Serice Management application serer in a distributed enironment. 22 Jazz for Serice Management: Configuration Guide Draft

33 Chapter 4. Configuring Administration Serices You must configure Administration Serices for secure access to all its features. You must also use the Administration Serices command-line interface to register the administration serice proider and managed systems as resources with the administration serice proider. You must then deploy tasks in task bundles by also using the CLI. Security configuration During installation, Administration Serices is configured to use basic authentication oer HTTPS. The basic authentication mechanism allows you to access the operations by using a web browser, which prompts you to proide a alid user ID and password for authentication purposes. The HTTPS authentication mechanism allows you to access the operations by using a web browser, which prompts you to select a alid client certificate for authentication purposes. This authentication mechanism requires you to connect to the secured port (HTTPS), and it redirects all the traffic from the unsecured port (HTTP) to the secured port (HTTPS). Administration serice proider registration During installation, the administration serice proider is registered as an OSLC serice proider in the proider registry. You can also manually register and unregister the administration serice proider by using the Administration Serices CLI. Managed system registration During the installation, Registry Serices, Dashboard Application Serices Hub, or Tioli Common Reporting are registered as managed resources with the administration serice proider. You can also manually register the managed systems as resources with the administration serice proider by using the Administration Serices command-line interface. You might also need to create custom serice types before you register managed systems. Task bundle deployment During the installation, the Registry Serices, Dashboard Application Serices Hub, or Tioli Common Reporting task bundles are installed only if their integration serices are installed in the same installation location as Administration Serices. You can deploy configuration tasks in task bundles by using the Administration Serices CLI. Note: Fix Pack 1 Although Administration Serices supports single sign-on (SSO), health check and automation administration tasks use command-line interfaces to run commands. The CLIs require credentials to be proided before the administration task can be completed; therefore, SSO is not supported for these administration tasks. Copyright IBM Corp. 2012,

34 Administration Serices roles Administration Serices has a set of roles that goern the access to its applications and operations. Administration Serices users hae no access priileges to administration serice proider or the UI until their user IDs are assigned to one of the Administration Serices roles. The following tables outline the set of roles and maps them to the operations of the administration serice proider. Table 2. Administration Serices roles and administration serice proider operations Role Administration serice proider operations Register serice proider Unregister serice proider Register resource PlatformMonitor No No No No PlatformOperator Yes Yes No No PlatformConfigurator No No Yes Yes PlatformAdministrator Yes Yes Yes Yes Unregister resource Table 3. Administration Serices roles, and administration serice proider and UI operations Role Administration serice proider and UI operations View resources View task details View task Deploy task Update task Delete task Run task PlatformMonitor Yes Yes Yes No No No No Yes PlatformOperator Yes Yes Yes No No No No Yes PlatformConfigurator Yes Yes Yes Yes Yes Yes Yes Yes PlatformAdministrator Yes Yes Yes Yes Yes Yes Yes Yes View job status Administration Serices client The Administration Serices client proides a command-line interface to manage registration of the administration serice proider, its managed resources, and tasks. When you register the administration serice proider, the Administration Serices client connects to the Registry Serices application and registers the administration serice proider as a serice proider in the proider registry. When you deploy the task bundle to the Administration Serices application serer, the Administration Serices client performs the following functions: Validates the format of the task bundle Extracts the contents of the task bundle to the location as specified in the properties file Reads in the plugin.xml file of the task bundle and parses it to retriee the required attributes of the tasks Stores the required attributes in the task Jaa bean Generates the RDF for each task after population of the task bean, and uses the WINK client to send the RDF to administration serice proider 24 Jazz for Serice Management: Configuration Guide Draft

35 The response with the task RDF payload is returned to the Administration Serices client. Configuring the Administration Serices client Before you register the administration serice proider and deploy a task bundle for a management system, you must configure the properties that the Administration Serices client uses. Procedure 1. Browse to the ADMIN_HOME/etc/ConfigSericeProider/conf directory. 2. Open the sericeproider.properties file. 3. Set the following properties for the Administration Serices client as required: Option client.log.file client.log.leel client.tasktable.width client.timeformat Description The relatie path and file name for the log file of the Administration Serices client. The default alue is./logs/configclient.log. The leel of logging to the log file. The Administration Serices client supports Jaa logging leels. The default alue is INFO. Other alid alues are: WARNING SEVERE FINE FINER FINEST ALL The width of the task table that is displayed in the command window. The default width is 80 characters. The minimum width is 15 characters. The date and time formats for the Administration Serices client, such that all dates and times are displayed in the specified date and time formats. The default alue is the MM-dd-yyyy HH\:mm\:SSS formats. 4. Ensure that the following properties are set for the Registry Serices application as required: Option oslc.registry.context oslc.registry.host oslc.registry.port Description The context root for the Registry Serices application. The default alue is oslc. The fully qualified host name or IP address on which the Registry Serices application is deployed. The default alue is localhost if Registry Serices and Administration Serices are deployed on the same application serer. The listening port for the Registry Serices application. The default alue can be: 9443 if Registry Serices application is deployed to its own WebSphere Application Serer profile if all Serices are installed and deployed on the same application serer and the protocol is HTTPS Chapter 4. Configuring Administration Serices 25

36 Option oslc.registry.protocol Description The protocol to connect to the Registry Serices application. The default alue is HTTPS. 5. Ensure that the following properties are set for Administration Serices as required: Option oslc.sericeproider.context oslc.sericeproider.host oslc.sericeproider.port oslc.sericeproider.protocol Description The context root for Administration Serices. The default alue is admin. The fully qualified host name or IP address on which Administration Serices is deployed. The default alue is localhost. The listening port for Administration Serices. The default alue can be: 9080 if Administration Serices is deployed to its own WebSphere Application Serer profile if all Serices are installed and deployed on the same application serer and the protocol is HTTPS The protocol to connect to Administration Serices. The default alue is HTTPS. Administration Serices properties The Admin_Home/etc/ConfigSericeProider/conf/sericeProider.properties file contains the properties for the Administration Serices client, administration serice proider, and the properties to connect to the Registry Serices application serer. Administration Serices client properties client.log.file= path/config_client_log_file.log The path and file name for the Administration Serices client log file. The default alue is the./logs/configclient.log file in the ADMIN_HOME directory. client.log.leel= Jaa_log_leel The trace leel for the Administration Serices client messages and errors that are logged to the log file. The default is the INFO leel. The alid alues are: INFO WARNING SEVERE FINE FINER FINEST ALL client.tasktable.width= table_width The width of the task table that is displayed in the command window. The default width is 80 characters. The minimum width is 15 characters. client.timeformat= date_format time_format The date and time formats for the Administration Serices client, such that all dates and times are displayed in the specified date and time formats. The default alue is the MM-dd-yyyy HH\:mm\:SSS formats. 26 Jazz for Serice Management: Configuration Guide Draft

37 Registry Serices application properties oslc.registry.context= context_root The context root for the Registry Serices application. The default alue is oslc. oslc.registry.host= host_name The host name or IP address on which the Registry Serices application is deployed. The default alue is localhost if the Registry Serices and Administration Serices applications are deployed on the same application serer. oslc.registry.port= port_number The listening port for the Registry Serices application. The default alue can be: 9443 if Registry Serices application is deployed to its own WebSphere Application Serer profile if all Serices are installed and deployed on the same application serer and the protocol is HTTPS oslc.registry.protocol= HTTP HTTPS The protocol to connect to the Registry Serices application. The default alue is HTTPS. Administration serice proider properties oslc.sericeproider.context= context_root The context root for administration serice proider. The default alue is FAS. oslc.sericeproider.host= host_name The host name or IP address on which administration serice proider is deployed. The default alue is localhost. oslc.sericeproider.port= port_number The listening port for administration serice proider. The default alue can be: 9080 if Administration Serices is deployed to its own WebSphere Application Serer full profile 8080 if Administration Serices is deployed to its own WebSphere Liberty profile if all Serices are installed and deployed on the same application serer and the protocol is HTTPS oslc.sericeproider.protocol= HTTP HTTPS The protocol to connect to Administration Serices administration serice proider. The default alue is HTTPS. Administration Serices command-line interface The adminserices command-line interface runs the Administration Serices client so that you can register or unregister the administration serice proider and managed resources. You can also deploy, iew, update, delete, or run tasks in task bundles. Syntax adminserices.bat sh -operation_name [operation_alue] [-option_name option_alue] Chapter 4. Configuring Administration Serices 27

38 Administration serice proider operations You can use these operations to register or unregister the administration serice proider. -register -register operation on page 29 -unregister -unregister operation on page 30 Managed resources operations You can use these operations to register or unregister the managed resources of the administration serice proider. -registerresource [response_file_path] -registerresource operation on page 29 -unregisterresource resource_id -unregisterresource operation on page 30 -iewresources resource_id -iewresources operation on page 31 Task and task bundle operations You can use these operations to deploy, iew, update, delete, or run tasks in task bundles. -deletetasks task_id -filter filter_alue -deletetasks operation on page 31 -installtasks task_bundle_path[-filter filter_alue][-parameters response_file_path] -installtasks operation on page 32 -runtasks task_id -filter filter_alue -runtasks operation on page 32 -iewtasks [task_id][ -filter filter_alue] -iewtasks operation on page 32 -iewtaskdetails task_id -iewtaskdetails operation on page 33 Other operations These operations proide general information. -buildinfo -buildinfo operation on page 33 -help -help operation on page 33 Filter options -filter filter_alue -filter option on page Jazz for Serice Management: Configuration Guide Draft

39 Security options Use these options with the supported operation. -ltpa token_id -ltpa operation on page 34 -ltpa2 token_id -ltpa2 operation on page 35 -username user_id -password password -username and -password options on page 34 -register operation The -register operation registers the Administration Serices administration serice proider in the proider registry. adminserices -register If basic authentication is enabled for Administration Serices, the user ID and password must be proided to successfully register the administration serice proider. The user ID must be preiously mapped to the PlatformAdministrator administrator role for Administration Serices. adminserices -register -username user_id -password password When the administration serice proider is registered, the following message is displayed in the command line: The administrator serice proider is registered and it is aailable at myserer.companydomain.com is the fully qualified host name of the serer on which Registry Serices application is installed. adminserices_proider_id is the unique identifier for the administration serice proider. -registerresource operation The -registerresource operation registers the specified resource with the administration serice proider. Each resource is registered in the resource registry. It has the following ariants: Registers the resource: adminserices -registerresource When you run the operation without a alue, you can interactiely specify the details for the resource that is based on properties outlined in Table 4. Table 4. Resource details Property ersion name identifier DependsOnURLs description Description Resource ersion Unique resource name Unique identifier for the resource Dependencies for the resource Description for the resource Chapter 4. Configuring Administration Serices 29

40 Table 4. Resource details (continued) Property adminsericestype Description Type of serice management system that the resource represents, with the following alid options: 1 ITM 2 Omnibus 3 TCR 4 DASH 5 FRS 6 Other (user_defined_serice_type) Registers the resource by the fully qualified path and response file, as specified by response_file_path alue, that contains the properties as outlined in Table 4 on page 29: adminserices -registerresource response_file_path For example, the operation registers Tioli Common Reporting, as defined by the tcr.response file. The serice management system type is TCR: adminserices.bat -registerresource c:/program Files/IBM/JazzSM/ar/admin_task_bundles/tcr.response Note: Administration Serices proides sample response files in the JazzSM_HOME/ar/admin_task_bundles directory that you can use as reference. -unregister operation The -unregister operation unregisters the Administration Serices administration serice proider from the proider registry and its resources from the resource registry. adminserices -unregister If basic authentication is enabled for Administration Serices, the user ID and password must be proided to successfully unregister the administration serice proider. The user ID must be preiously mapped to the PlatformAdministrator administrator role for Administration Serices. adminserices -unregister -username user_id -password password When the administration serice proider is unregistered, the following message is displayed in the command line: The administration serice proider and its resources hae been unregistered. -unregisterresource operation The -unregisterresource operation unregisters the managed resource, as specified by the resource_id, from the administration serice proider, and deletes the resource from the resource registry. adminserices -unregisterresource resource_id If basic authentication is enabled for Administration Serices, the user ID and password must be proided to successfully unregister the administration serice 30 Jazz for Serice Management: Configuration Guide Draft

41 proider. The user ID must be preiously mapped to the PlatformAdministrator administrator role for Administration Serices. adminserices -unregisterresource resource_id -username user_id -password password When the managed resource is unregistered, the following message is displayed in the command line: The resource has been unregistered. -iewresources operation The -iewresources operation displays one or more resources that are registered with the administration serice proiders. If basic authentication is enabled for Administration Serices, the user ID and password must be proided to iew registered resources. The user ID must be preiously mapped to the PlatformAdministrator administrator role for Administration Serices. It has following ariants: Displays all resources that are registered with the administration serice proider: adminserices -iewresources Displays the registered resource as specified by the resource_id alue: adminserices -iewresources resource_id Table 5 summarizes the output for the -iewresources operation. Table 5. iewresources output Column name Product Version Status Description The cell contains: Identifier: The unique identifier for the resource. Name: The name of the resource. Description: The description of the resource. The ersion of the resource. The status of the resource at the specified date and time. -deletetasks operation The -deletetasks operation deletes one or more tasks. You must confirm deletion. It has the following ariants: Deletes the registered task as specified by the task ID alue: adminserices -deletetasks task_id Deletes one or many tasks as specified by the filter_alue filter alue: adminserices -deletetasks -filter filter_alue When the task is deleted, the following message is displayed in the command line: Task task_id deleted successfully. Chapter 4. Configuring Administration Serices 31

42 -installtasks operation The -installtasks operation deploys one or more tasks in the task bundle to the Administration Serices application serer. Each task is registered in the resource registry. It has the following ariants: Deploys all tasks in a task bundle. adminserices -installtasks task_bundle_path For example: adminserices -installtasks c:\tmp\csp\mgmtsys\taskbundle\task_bundle.zip Deploys all tasks in a task bundle with the static parameters either specified interactiely or silently by using the response file as specified by response_file_path alue. adminserices -installtasks task_bundle_path -parameters [response_file_path] For example: adminserices -installtasks c:\tmp\csp\mgmtsys\taskbundle\task_bundle.zip -parameters c:\tmp\csp\mgmtsys\taskparameters.response The task parameters response file specifies static parameters as name-alue pairs. Updates the registered tasks as specified by the filter alue with new ersions of the tasks in the specified task bundle. When you update a task bundle, the Administration Serices client first deletes the old ersion of the tasks in the task bundle and then installs the new ersions. adminserices -installtasks task_bundle_path -filter filter_alue For example: adminserices -installtasks c:\tmp\csp\mgmtsys\taskbundle\task_bundle.zip -filter taskid For each task installed, the following messages are displayed in the command line: Installing task task_id on the admin/admin/serices/tasks/collection. serer. Task task_id Installed successfully. myserer.companydomain.com:port is the fully qualified host name and port of the serer on which Administration Serices is installed. -runtasks operation The -runtasks operation runs one or more tasks. It has the following ariants: Runs the registered task as specified by the task_id alue: adminserices -runtasks task_id Runs the set of registered tasks as specified by the filter_alue filter alue: adminserices -runtasks -filter filter_alue -iewtasks operation The -iewtasks operation displays one or more tasks. It has following ariants: Displays the registered tasks of the administration serice proider. adminserices -iewtasks Displays the registered task as specified by the task_id alue: adminserices -iewtasks task_id Displays one or more registered tasks as specified by the filter_alue filter alue: adminserices -iewtasks -filter filter_alue 32 Jazz for Serice Management: Configuration Guide Draft

43 Table 6 summarizes the output for the -iewtasks operation for each task. Table 6. iewtasks output Column name Task Product Status Description The cell contains: Identifier: The unique identifier for the task. Name: The name of the task. The name of the managed resource that is associated with the task. The status of the task at the specified date and time. -iewtaskdetails operation The -iewtasksdetails operation displays the details of the registered task as specified by the task_id alue. adminserices -iewtaskdetails task_id Table 7 summarizes the output for the -iewtaskdetails operation for each task. Table 7. iewtasksdetails output Details Task Status Name Description Product Execution time Description The unique identifier for the task. The status of the task at the specified date and time. The name of task. The description for the task. The name of the managed resource that is associated with the task. The last date and time on which the task was last run. -help operation The -help operation displays the help for the Administration Serices CLI in the command window. adminserices -help -buildinfo operation The -buildinfo operation displays the build information for the Administration Serices CLI and administration serice proider in the command window. adminserices -buildinfo If basic authentication is enabled for Administration Serices, the user ID and password must be proided to successfully unregister the administration serice proider. The user ID must be preiously mapped to the PlatformAdministratorRole administrator role for Administration Serices. adminserices -buildinfo -username user_id -password password Chapter 4. Configuring Administration Serices 33

44 The following information is displayed in the command line: The following build information has been retrieed: Client: client_build_number Administration serice proider: configuration_serice_proider_build_number -filter option The -filter option proides filter criteria for the specified operation. A filter can hae one or many filter alues, with each new filter alue joined to the filter expression by using a logical AND operator. -filter filter_alue [filter_alue] Table 8 summarizes the filter options and alid alues that are delimited by a colon. Table 8. Filter options Filter option identifier: name: description: target: Value Task identifier Task name Task description Type of serice management system that the resource represents, with the following alid options: ITM Omnibus TCR DASH FRS user_defined_serice_type The following example returns all tasks that hae derby in their task identifiers: adminserices -iewtasks -filter identifier:derby -username and -password options The -username and -password options allow authentication for secure access to Administration Serices, so the specified user_id can run the adminserices command and its operations if that user has sufficient priileges. -username user_id -password password -ltpa operation The -ltpa operation specifies the LTPA Version 1 token as specified by the token_id alue for single sign-on. If both ersion 1 and 2 tokens are specified, precedence is gien to the more secure LTPA2 ersion. adminserices -register -ltpa token_id 34 Jazz for Serice Management: Configuration Guide Draft

45 -ltpa2 operation The -ltpa2 operation specifies the LTPA Version 2 token as specified by the token_id alue for single sign on. If both ersion 1 and 2 tokens are specified, precedence is gien to the more secure LTPA2 ersion. adminserices -register -ltpa2 token_id Administration serice proider The administration serice proider is an Administration Serices component that integrates with Registry Serices to register serice management systems as resources. It also manages data about the configuration tasks that are associated with these managed resources. Administration Serices exposes the administration serice proider as an OSLC serice proider and registers it as a serice proider in the proider registry. The administration serice proider is deployed to the Administration Serices application serer and proides the following features by using RESTful serices: Ability to manually register and unregister the administration serice proider in the proider registry Ability to register and unregister resources of the administration serice proider in the resource registry Ability to install configuration tasks for resources in the resource registry Ability to run the registered tasks for the associated resources Registering the administration serice proider You can register the administration serice proider in the proider registry by using the Administration Serices CLI register operation. Before you begin Ensure that the properties used by the Administration Serices CLI are set and that authentication mechanism is configured. Procedure 1. Open a command window and browse to ADMIN_HOME/bin. 2. Run the adminserices CLI with the -register operation for your operating system as follows: Option On Windows systems On Linux systems Description adminserices.bat -register./adminserices.sh -register If basic authentication is enabled for Administration Serices, the user ID and password must be proided to successfully register the administration serice proider. The user ID must be preiously mapped to the PlatformAdministrator administrator role for Administration Serices. 3. Enter the user name and then the password. The Administration Serices client returns the URI for the administration serice proider when it is successfully registered in the proider registry. Chapter 4. Configuring Administration Serices 35

46 Unregistering the administration serice proider You can unregister the administration serice proider from the proider registry and delete its managed resources from the resource registry by using the Administration Serices CLI unregister operation. Before you begin Ensure that the properties used by the Administration Serices CLI are set and that authentication mechanism is configured. Procedure 1. Open a command window and browse to ADMIN_HOME/bin. 2. Run the adminserices CLI with the -unregister operation for your operating system as follows: Option On Windows systems On Linux systems Description adminserices.bat -unregister./adminserices.sh -unregister If basic authentication is enabled for Administration Serices, the user ID and password must be proided to successfully register the administration serice proider. The user ID must be preiously mapped to the PlatformAdministrator administrator role for Administration Serices. 3. Enter the user name and then the password. The Administration Serices client returns a message that the administration serice proider and its managed resources are successfully unregistered. Managed resources of the administration serice proider You can register resources with the administration serice proider by using the Administration Serices client. A managed resource is also known as a managed system. When you register a resource with the administration serice proider, Administration Serices creates a registration record in the resource registry to register the resource that the administration serice proider manages. When you register multiple resources and if the name and identifier of these resources are the same, they are reconciled as a single resource; hence, they appear only once on the Administration Serices UI. Howeer, you can execute the tasks from all administration serice proiders. Registering resources interactiely You can interactiely register the resources that are managed by the administration serice proider by using the Administration Serices CLI registerresource operation. The Administration Serices client prompts you for the resource details. Before you begin Ensure that the properties used by the Administration Serices CLI are set and that the authentication mechanism is configured. Procedure 1. Open a command window and browse to ADMIN_HOME/bin. 36 Jazz for Serice Management: Configuration Guide Draft

47 2. Run the adminserices CLI for your operating system with the -registerresource operation. Option On Windows systems On Linux systems Description adminserices.bat -registerresource./adminserices.sh -registerresource 3. When prompted, enter the following details: Prompt Resource identifier Resource name Resource description Resource dependencies Valid alues All characters except space, comma, and quotes. String, for example, Tioli Common Reporting String, for example, Reporting system Empty or one or many resources that are separated by a comma Resource ersion String, for example, Serice type Integer in the range of 1 to number, with the following alid options: 1 ITM 2 Omnibus 3 TCR 4 DASH 5 FRS 6 Other Note: Select Other to add custom or user-defined serice type. The Administration Serices client updates the new serice type in the SericeType property of the AdministrableResource.input file. This alue can be used when you register the serice management system as a resource and when you specify the target for the task bundle. 4. When authentication is enabled for the Administration Serices, you must specify a user name with appropriate priileges and the associated password. Note: This user must be mapped to either the PlatformOperator or PlatformAdministrator Administration Serices roles. The Administration Serices client returns the URI for the resource when it is successfully registered with the administration serice proider. Related reference: Administration Serices command-line interface The adminserices command-line interface runs the Administration Serices client so that you can register or unregister the administration serice proider and managed resources. You can also deploy, iew, update, delete, or run tasks in task bundles. Chapter 4. Configuring Administration Serices 37

48 Registering resources silently You can silently register the resources that are managed by the administration serice proider by using the Administration Serices CLI registerresource operation. The Administration Serices client uses a resource registration response file to register the resource. Before you begin Ensure that the properties used by the Administration Serices CLI are set and that the authentication mechanism is configured. Procedure 1. Open a command window and browse to ADMIN_HOME/bin. 2. Create a resource registration response file, with a file extension of.response and sae it to a directory, for example, c:/taskbundleresponse 3. Run the adminserices CLI for your operating system with the -registerresource operation, and specify the name of the resource registration response file. Option On Windows systems Description adminserices.bat -registerresource response_file_path [-username user_id -password password] For example: adminserices.bat -registerresource c:/taskbundleresponse/tcr.response On Linux and AIX systems./adminserices.sh -registerresource response_file_path [-username user_id -password password] For example:./adminserices.sh -registerresource /opt/taskbundleresponse/tcr.response When authentication is enabled for Administration Serices, you must specify a user name with appropriate priileges and the associated password. Use the -username and -password options in the command line; otherwise, you are prompted for them. This user must be mapped to either the PlatformOperator or PlatformAdministrator Administration Serices roles. The Administration Serices client returns a message to state that resource with the specified unique ID in the response file is created. Related reference: Administration Serices command-line interface The adminserices command-line interface runs the Administration Serices client so that you can register or unregister the administration serice proider and managed resources. You can also deploy, iew, update, delete, or run tasks in task bundles. Resource registration response file Use a response file to register a resource that is managed by the administration serice proider in the resource registry. 38 Jazz for Serice Management: Configuration Guide Draft

49 Adding custom serice types You can add custom or user-defined serice types to represent the serice management systems in your integrated serice management enironment in the AdministrableResource.input file. About this task When a serice management system is registered as a managed resource of the serice proider for Administration Serices, the registration includes specifying the type of serice management system. The serice types maps the task bundle to the managed resource, also known as the managed system. Administration Serices currently supports the following predefined serice types: ITM, representing a monitoring management system type Omnibus, representing an operations management system type TCR, representing as the reporting management system type DASH, representing a UI management system type FRS, representing a linked data management system type These serice types are defined in thesericetype property in the AdministrableResource.input file, with each type delimited by using the pipe symbol: SericeType={ITM Omnibus TCR DASH FRS}+ You can define custom serice types to represent the serice management systems in your integrated serice management enironment; howeer, you must ensure that you use this alue when you register the serice management system as a resource and when you specify the target for the task bundle. Procedure 1. Browse to the ADMIN_HOME/etc/ConfigSericeProider/templates directory. 2. Open the AdministrableResource.input file in a text editor. 3. Edit the alue for the SericeType property to specify the user-defined serice type. Add the alue in between the curly braces that are separated by pipe ' '. SericeType={ITM Omnibus TCR DASH FRS}+ For example, to specify a custom serice type for business serice management system, enter: SericeType={ITM Omnibus TCR DASH FRS BSM}+ 4. Sae the file. Resource registration response file Use a response file to register a resource that is managed by the administration serice proider in the resource registry. Create a resource registration response file, with a file extension of.response and sae it to a directory, for example, c:/taskbundleresponse. Table 9. Properties in the resource registration response file Property ersion name Description Resource ersion Unique resource name Chapter 4. Configuring Administration Serices 39

50 Table 9. Properties in the resource registration response file (continued) Property identifier DependsOnURLs description SericeType Description Unique identifier for the resource Dependencies for the resource Description for the resource Type of serice management system that the resource represents, with the following alid options: 1 ITM 2 Omnibus 3 TCR 4 DASH 5 FRS number user_defined_serice_type Examples This example shows the content of the TCR.response file. When you run the Administration Serices client with the -registerresource operation and this file, it registers the IBM Tioli Common Reporting resource in the resource registry. SericeType=TCR identifier=20 description=tioli Common Reporting proides an integrated reporting solution for the products in the Tioli portfolio. TCR allows to link multiple reports across arious Tioli products to simplify the report naigation and accelerate access to key reporting information. name=ibm Tioli Common Reporting ersion=3.1 DependsOnURLs= Note: To use a DBCS locale like Japanese, Chinese or Korean, the DBCS locale-specific content in the response file must be in the Unicode format. Response file in a Unicode format: SericeType=ITM identifier=128 description=\u00e3\ufffd\u201c\u00e3\u201a\u0152\u00e3\ufffd \u00af\u00e3\u20ac\ufffd\u00e6\u2014\u00a5\u00e6\u0153\u00ac \u00e3\ufffd\u00ae\u00e8\u00a3\u00bd\u00e5\u201c\ufffd\u00e3 \ufffd\u00a7\u00e3\ufffd\u2122 name=jp\u00e8\u00a3\u00bd\u00e5\u201c\ufffd ersion=2.1 DependsOnURLs= Rehosting the Registry Serices Before you rehost or moe the Registry Serices, you must perform certain steps to ensure that the Administration Serices work well with the new Registry Serices configuration. Procedure 1. Stop the Administration Serices UI and all the administration serice proiders. 40 Jazz for Serice Management: Configuration Guide Draft

51 Tasks and task bundles 2. Rehost Registry Serices by updating the new registry configuration in the adminsericeshui.properties and sericeproider.properties files. 3. Start all the administration serice proiders. 4. Start the Administration Serices UI. A task is a small program or script that can run independently to perform an operation on a managed system. A task bundle is a plug-in that contains the configuration tasks. The tasks in the task bundle are deployed to Administration Serices. You can use the Administration Serices client to deploy tasks in a task bundle, update tasks, and delete tasks. You can also use it to iew and run tasks; alternatiely, you can use the Administration Serices UI to iew and run them. Related concepts: Tasks A task is a small program or script that can run independently to perform an action on the managed system, for example, check the optimal heap size for the managed system. Each task might require parameters to be entered before it is run. Task bundles A task bundle is a plug-in that contains the configuration tasks that can be performed on the managed systems. The tasks in the task bundle are deployed to Administration Serices. Administration Serices proides task bundles for the following serice management systems: Registry Serices, Dashboard Application Serices Hub, and Tioli Common Reporting. These task bundles contain configuration tasks that can be used for actiities such as modifying configuration settings and monitoring the system health of serice management systems. When you install Administration Serices with Registry Serices, Dashboard Application Serices Hub, or Tioli Common Reporting, Administration Serices registers these serice management systems as managed resources and deploys the respectie task bundle. The registered resources that are also known as managed systems are displayed in the Applications iew of the Administration Serices UI. When you select a managed system in the Applications iew, the tasks that are associated with the managed system are displayed in the Administration Tasks iew. Each task is associated a help; when you select a task in the Administration Tasks iew, the task help is displayed in the Help tab of the Administration Task Details iew. Tasks A task is a small program or script that can run independently to perform an action on the managed system, for example, check the optimal heap size for the managed system. Each task might require parameters to be entered before it is run. You can use the Administration Serices UI or the Administration Serices command-line interface to deploy a task bundle that contains tasks for a managed system. It is also used to update tasks if new ersions are aailable. Alternatiely, you can use Manage Tasks in the Administration Tasks iew to deploy and update task bundles that contain tasks, and delete tasks for a managed system. Manage Tasks is a self-management task that is proided by Administration Chapter 4. Configuring Administration Serices 41

52 Serices for all managed system. This task is isible in the Administration Tasks iew after you register managed systems with the administration serice proider. You can use the Administration Serices UI or Administration Serices command-line interface to iew these tasks. Table 10 summarizes the details about each task that can be displayed: in the table in the Administration Tasks iew in the pop-up window, when you hoer oer any cell in the table of the Administration Tasks iew in the Administration Task Details iew, when you select the task in the table of the Administration Tasks iew in the command window, when you run the iewtaskdetails or iewtasks operations with the Administration Serices command-line interface Table 10. Task details Attribute Description Name The display name for the task. Status The status of the task, such as OK or Running. Product The name of the associated managed system. Last updated The date and time on which the task status was last updated or the task action was run. Version The ersion of the task. Description The description of the task. Administration Task Details iew or iewtaskdetails operation only Product The name of the associated managed system. Product ersion The ersion of the managed system. Target The product on which the task is performed. Name The display name for the task. Version The ersion of the task. Description The description of the task. Last updated The date and time on which the task status was last updated or the task action was run. Task Status Details The description of the task status. Task Message details The details of the task execution. You can use the Administration Serices UI or Administration Serices command-line interface and run these tasks to erify the configuration of the managed system or configure the managed system, as follows: Use the Actions > Run Automation or Actions > Run Health Check menu items after you select the tasks in the Administration Tasks iew Use the runtasks operation with the Administration Serices command-line interface Deploying task bundles from the command line You can deploy tasks in the task bundle by using the Administration Serices CLI installtasks operation. 42 Jazz for Serice Management: Configuration Guide Draft

53 Before you begin Ensure that you configure the Administration Serices client before you deploy any task bundles. Procedure 1. Open a command window and browse to ADMIN_HOME/bin. 2. Run the adminserices CLI for your operating system with the -installtasks operation, and specify the fully qualified path and file name for the task bundle. The task bundle might require that you specify static parameters when you deploy the task bundle by using the -installtasks option. You specify them either interactiely or silently by using the response file, as specified the response_file_path alue. Option On Windows systems Description adminserices.bat -installtasks task_bundle_path [-parameters response_file_path] For example, the alue for task_bundle_path is c:\\tmp\\csp\\mgmtsys\\taskbundle\\ task_bundle.zip and c:\\tmp\\csp\\ mgmtsys\\taskparameters.response is the response_file_path alue. On Linux systems./adminserices.sh -installtasks task_bundle_path [-parameters response_file_path] Where the alue for task_bundle_path is for example: \tmp\csp\mgmtsys\taskbundle\ task_bundle.zip For example, the alue for task_bundle_path is /tmp/csp/mgmtsys/task_bundle.zip and /tmp/csp/mgmtsys/taskparameters.response is the response_file_path alue. Note: If you did not specify the task parameter response file, you are prompted for the alues for the static parameters. 3. When authentication is enabled for Administration Serices, you must specify a user name with appropriate priileges and the associated password. Note: This user must be mapped to either the PlatformConfigurator or PlatformAdministrator Administration Serices roles. Updating tasks from the command line You can update deployed tasks by using the Administration Serices CLI installtasks operation. It updates the set of tasks from the specified task bundle. About this task When you update a task, the Administration Serices client first deletes the old ersion of the task and then installs the new ersion. Chapter 4. Configuring Administration Serices 43

54 Procedure 1. Open a command window and browse to ADMIN_HOME/bin. 2. Run the adminserices CLI for your operating system with the -installtasks operation, and specify the fully qualified path and file name for the task bundle and the filter. Option On Windows systems Description adminserices.bat -installtasks task_bundle_path -filter filter_alue Where the alue for task_bundle_path is for example: c:\\tmp\\csp\\mgmtsys\\ taskbundle\\task_bundle.zip and the alue for filter_alue is, for example, identifier:derby. On Linux systems./adminserices.sh -installtasks task_bundle_path -filter filter_alue Where the alue for task_bundle_path is for example: \tmp\csp\mgmtsys\taskbundle\ task_bundle.zip and the alue for filter_alue is, for example, identifier:derby. 3. When authentication is enabled for Administration Serices, you must specify a user name with appropriate priileges and the associated password. Note: This user must be mapped to either the PlatformConfigurator or PlatformAdministrator Administration Serices roles. Deleting tasks from the command line You can delete tasks by using the Administration Serices CLI deletetasks operation. The Administration Serices client can delete a single task or multiple tasks that are based on the specified filter. Procedure 1. Open a command window and browse to ADMIN_HOME/bin. 2. Run the adminserices CLI for your operating system with the -deletetasks operation. Option Description On Windows systems Delete a single task that is based on the task identifier: adminserices.bat -deletetasks task_id Where the task_id alue is, for example, TCR-derby-logging-leel-check. Delete one or many tasks that are based on the filter alue: adminserices.bat -deletetasks -filter filter_alue Where the filter_alue alue is, for example, identifier:derby. 44 Jazz for Serice Management: Configuration Guide Draft

55 Option Description On Linux systems Delete a single task that is based on the task identifier:./adminserices.sh -deletetasks task_id Where the task_id alue is, for example, TCR-derby-logging-leel-check. Delete one or many tasks that are based on the filter alue:./adminserices.sh -deletetasks -filter filter_alue Where the filter_alue alue is, for example, identifier:derby. 3. When authentication is enabled for Administration Serices, you must specify a user name with appropriate priileges and the associated password. Note: This user must be mapped to either the PlatformConfigurator or PlatformAdministrator Administration Serices roles. Configuring the connection to the Registry Serices application You can update the connection properties that Administration Serices UI uses to connect to the Registry Serices application, if there are any changes for this serer in your enironment, for example a new application serer for the Registry Serices application. About this task The connection properties to the Registry Serices application serer are set when you first install Administration Serices UI. Procedure 1. Browse to the ADMINUI_HOME/etc/AdminSericesGUI/conf directory. 2. Open the adminsericesgui.properties file. 3. Set the following properties for the Registry Serices application serer as required: Option registry.context registry.host registry.port Description The context root for the Registry Serices application. The host name or IP address on which the Registry Serices application is deployed. The default alue is localhost if the Registry Serices and Administration Serices UI applications are deployed on the same application serer. The listening port for the Registry Serices application. The default alue is 9443 or if all Serices are installed and deployed on the same application serer and the protocol is HTTPS. Chapter 4. Configuring Administration Serices 45

56 Option registry.protocol Description The protocol to connect to the Registry Serices application. The default alue is HTTPS. Administration Serices UI properties The ADMINUI_HOME>/etc/AdminSericesGUI/conf/adminsericesgui.properties file contains the properties that Administration Serices UI uses to connect to the Registry Serices application serer. registry.context= context_root The context root for the Registry Serices application. The default alue is FRS. registry.host= host_name The host name or IP address on which the Registry Serices application is deployed. The default alue is localhost if the Registry Serices and Administration Serices UI applications are deployed on the same application serer. registry.port= port_number The listening port for the Registry Serices application. The default alue is 9443 or if all Serices are installed and deployed on the same application serer and the protocol is HTTPS. registry.protocol= HTTP HTTPS The protocol to connect to the Registry Serices application. The default alue is HTTPS. Administration Serices Base Edition Fix Pack 1 The Administration Serices Base Edition is a Administration Serices package that proides the command-line interface to work with Administration Serices tasks. Choose the Administration Serices Base Edition package if you want to ealuate the features that are proided by Administration Serices. The Administration Serices Base Edition command-line interface proides capabilities similar to that of the Administration Serices client, except that you cannot run administrator serice proider and managed resource operations. You can perform task and task bundle operations without registering resources with the administration serice proider. When you install Administration Serices, Installation Manager installs the Administration Serices Base Edition package AdminSericesBaseEdition_buildnumber.zip into the JazzSM_HOME/admin/tools directory. Related tasks: Administration Serices Base Edition command-line interface on page 49 You can use the Administration Serices Base Edition command-line interface to perform task and task bundle operations including deploy, iew, update, delete, and run tasks in task bundles. Related reference: 46 Jazz for Serice Management: Configuration Guide Draft

57 Task and task bundle operations Administration Serices Base Edition supports the following task and task bundle operations. You can run these operations without registering resources with the administration serice proider. Task and task bundle operations Fix Pack 1 Administration Serices Base Edition supports the following task and task bundle operations. You can run these operations without registering resources with the administration serice proider. Syntax adminserices.bat sh -operation_name -installtasks operation The -installtasks operation deploys one or more tasks in the task bundle to the Administration Serices application serer. Each task is registered in the resource registry. It has the following ariants: Deploys all tasks in a task bundle. adminserices -installtasks task_bundle_path For example: adminserices -installtasks c:\tmp\csp\mgmtsys\taskbundle\task_bundle.zip Deploys all tasks in a task bundle with the static parameters either specified interactiely or silently by using the response file as specified by response_file_path alue. adminserices -installtasks task_bundle_path -parameters [response_file_path] For example: adminserices -installtasks c:\tmp\csp\mgmtsys\taskbundle\task_bundle.zip -parameters c:\tmp\csp\mgmtsys\taskparameters.response The task parameters response file specifies static parameters as name-alue pairs. Updates the registered tasks as specified by the filter alue with new ersions of the tasks in the specified task bundle. When you update a task bundle, the Administration Serices client first deletes the old ersion of the tasks in the task bundle and then installs the new ersions. adminserices -installtasks task_bundle_path -filter filter_alue For example: adminserices -installtasks c:\tmp\csp\mgmtsys\taskbundle\task_bundle.zip -filter taskid For each task installed, the following messages are displayed in the command line: Installing task task_id on the admin/admin/serices/tasks/collection. serer. Task task_id Installed successfully. myserer.companydomain.com:port is the fully qualified host name and port of the serer on which Administration Serices is installed. Chapter 4. Configuring Administration Serices 47

58 -iewtasks operation The -iewtasks operation displays one or more tasks. It has following ariants: Displays the registered tasks of the administration serice proider. adminserices -iewtasks Displays the registered task as specified by the task_id alue: adminserices -iewtasks task_id Displays one or more registered tasks as specified by the filter_alue filter alue: adminserices -iewtasks -filter filter_alue Table 11 summarizes the output for the -iewtasks operation for each task. Table 11. iewtasks output Column name Task Product Status Description The cell contains: Identifier: The unique identifier for the task. Name: The name of the task. The name of the managed resource that is associated with the task. The status of the task at the specified date and time. -iewtaskdetails operation The -iewtasksdetails operation displays the details of the registered task as specified by the task_id alue. adminserices -iewtaskdetails task_id Table 12 summarizes the output for the -iewtaskdetails operation for each task. Table 12. iewtasksdetails output Details Task Status Name Description Product Execution time Description The unique identifier for the task. The status of the task at the specified date and time. The name of task. The description for the task. The name of the managed resource that is associated with the task. The last date and time on which the task was last run. -runtasks operation The -runtasks operation runs one or more tasks. It has the following ariants: Runs the registered task as specified by the task_id alue: adminserices -runtasks task_id Runs the set of registered tasks as specified by the filter_alue filter alue: 48 Jazz for Serice Management: Configuration Guide Draft

59 adminserices -runtasks -filter filter_alue -deletetasks operation The -deletetasks operation deletes one or more tasks. You must confirm deletion. It has the following ariants: Deletes the registered task as specified by the task ID alue: adminserices -deletetasks task_id Deletes one or many tasks as specified by the filter_alue filter alue: adminserices -deletetasks -filter filter_alue When the task is deleted, the following message is displayed in the command line: Task task_id deleted successfully. Related concepts: Deploying task bundles from the command line on page 42 You can deploy tasks in the task bundle by using the Administration Serices CLI installtasks operation. Related tasks: Updating tasks from the command line on page 43 You can update deployed tasks by using the Administration Serices CLI installtasks operation. It updates the set of tasks from the specified task bundle. Deleting tasks from the command line on page 44 You can delete tasks by using the Administration Serices CLI deletetasks operation. The Administration Serices client can delete a single task or multiple tasks that are based on the specified filter. Administration Serices Base Edition command-line interface Fix Pack 1 You can use the Administration Serices Base Edition command-line interface to perform task and task bundle operations including deploy, iew, update, delete, and run tasks in task bundles. Before you begin Copy the AdminSericesBaseEdition_buildnumber.zip package to the system where you want to use it, and extract the contents of the package into a temporary directory. Procedure 1. Open a command window and browse to tmp_dir/bin. 2. Set the JAVA_HOME enironment ariable for your operating system in the setsericeen.bat sh file and run this modified file. Note: If you hae the JAVA_HOME enironment ariable that is specified as a system enironment ariable, you do not need to run the setsericeen.bat sh file. 3. Run the Administration Serices Base Edition CLI for your operating system with the required operation. Chapter 4. Configuring Administration Serices 49

60 Option On Windows systems On Linux systems Description adminserices.bat -operation_name adminserices.sh -operation_name Related concepts: Deploying task bundles from the command line on page 42 You can deploy tasks in the task bundle by using the Administration Serices CLI installtasks operation. Related tasks: Updating tasks from the command line on page 43 You can update deployed tasks by using the Administration Serices CLI installtasks operation. It updates the set of tasks from the specified task bundle. Deleting tasks from the command line on page 44 You can delete tasks by using the Administration Serices CLI deletetasks operation. The Administration Serices client can delete a single task or multiple tasks that are based on the specified filter. 50 Jazz for Serice Management: Configuration Guide Draft

61 Chapter 5. Configuring the LTPA token timeout alue on the application serer You can configure the LTPA token timeout alue for each Jazz for Serice Management application serer in the WebSphereadministratie console. Before you begin Jazz for Serice Management application serer is enabled for single sign-on. About this task The default timeout for an LTPA token is 120 minutes. An LTPA timeout causes you to be logged out from the integration serice application. It can also cause an authentication popup message in Dashboard Application Serices Hub, if the first request after the timeout is an AJAX request from a widget. Note: You can also perform this task by running the Configuration: LTPA Token session TimeOut task from the Administration Serices task bundle for Dashboard Application Serices Hub. Procedure 1. Start the WebSphere administratie console; for example, select Start > IBM WebSphere > IBM WebSphere Application Serer > Profiles > JazzSMProfile > Administratie console. 2. Enter the WebSphere administrator user ID and password, and click Log in. 3. Click Security > Global security. 4. In the Authentication area of the Global security page, click the LTPA link. 5. In the LTPA timeout area of the LTPA page, edit the alue for the LTPA timeout. 6. Click Apply and then Apply. What to do next Remember: Repeat this procedure on each Jazz for Serice Management application serer in a distributed enironment. Copyright IBM Corp. 2012,

62 52 Jazz for Serice Management: Configuration Guide Draft

63 Chapter 6. Configuring Administration Serices You must configure Administration Serices for secure access to all its features. You must also use the Administration Serices command-line interface to register the administration serice proider and managed systems as resources with the administration serice proider. You must then deploy tasks in task bundles by also using the CLI. Security configuration During installation, Administration Serices is configured to use basic authentication oer HTTPS. The basic authentication mechanism allows you to access the operations by using a web browser, which prompts you to proide a alid user ID and password for authentication purposes. The HTTPS authentication mechanism allows you to access the operations by using a web browser, which prompts you to select a alid client certificate for authentication purposes. This authentication mechanism requires you to connect to the secured port (HTTPS), and it redirects all the traffic from the unsecured port (HTTP) to the secured port (HTTPS). Administration serice proider registration During installation, the administration serice proider is registered as an OSLC serice proider in the proider registry. You can also manually register and unregister the administration serice proider by using the Administration Serices CLI. Managed system registration During the installation, Registry Serices, Dashboard Application Serices Hub, or Tioli Common Reporting are registered as managed resources with the administration serice proider. You can also manually register the managed systems as resources with the administration serice proider by using the Administration Serices command-line interface. You might also need to create custom serice types before you register managed systems. Task bundle deployment During the installation, the Registry Serices, Dashboard Application Serices Hub, or Tioli Common Reporting task bundles are installed only if their integration serices are installed in the same installation location as Administration Serices. You can deploy configuration tasks in task bundles by using the Administration Serices CLI. Note: Fix Pack 1 Although Administration Serices supports single sign-on (SSO), health check and automation administration tasks use command-line interfaces to run commands. The CLIs require credentials to be proided before the administration task can be completed; therefore, SSO is not supported for these administration tasks. Copyright IBM Corp. 2012,

64 Administration Serices roles Administration Serices has a set of roles that goern the access to its applications and operations. Administration Serices users hae no access priileges to administration serice proider or the UI until their user IDs are assigned to one of the Administration Serices roles. The following tables outline the set of roles and maps them to the operations of the administration serice proider. Table 13. Administration Serices roles and administration serice proider operations Role Administration serice proider operations Register serice proider Unregister serice proider Register resource PlatformMonitor No No No No PlatformOperator Yes Yes No No PlatformConfigurator No No Yes Yes PlatformAdministrator Yes Yes Yes Yes Unregister resource Table 14. Administration Serices roles, and administration serice proider and UI operations Role Administration serice proider and UI operations View resources View task details View task Deploy task Update task Delete task Run task PlatformMonitor Yes Yes Yes No No No No Yes PlatformOperator Yes Yes Yes No No No No Yes PlatformConfigurator Yes Yes Yes Yes Yes Yes Yes Yes PlatformAdministrator Yes Yes Yes Yes Yes Yes Yes Yes View job status Administration Serices client The Administration Serices client proides a command-line interface to manage registration of the administration serice proider, its managed resources, and tasks. When you register the administration serice proider, the Administration Serices client connects to the Registry Serices application and registers the administration serice proider as a serice proider in the proider registry. When you deploy the task bundle to the Administration Serices application serer, the Administration Serices client performs the following functions: Validates the format of the task bundle Extracts the contents of the task bundle to the location as specified in the properties file Reads in the plugin.xml file of the task bundle and parses it to retriee the required attributes of the tasks Stores the required attributes in the task Jaa bean Generates the RDF for each task after population of the task bean, and uses the WINK client to send the RDF to administration serice proider 54 Jazz for Serice Management: Configuration Guide Draft

65 The response with the task RDF payload is returned to the Administration Serices client. Configuring the Administration Serices client Before you register the administration serice proider and deploy a task bundle for a management system, you must configure the properties that the Administration Serices client uses. Procedure 1. Browse to the ADMIN_HOME/etc/ConfigSericeProider/conf directory. 2. Open the sericeproider.properties file. 3. Set the following properties for the Administration Serices client as required: Option client.log.file client.log.leel client.tasktable.width client.timeformat Description The relatie path and file name for the log file of the Administration Serices client. The default alue is./logs/configclient.log. The leel of logging to the log file. The Administration Serices client supports Jaa logging leels. The default alue is INFO. Other alid alues are: WARNING SEVERE FINE FINER FINEST ALL The width of the task table that is displayed in the command window. The default width is 80 characters. The minimum width is 15 characters. The date and time formats for the Administration Serices client, such that all dates and times are displayed in the specified date and time formats. The default alue is the MM-dd-yyyy HH\:mm\:SSS formats. 4. Ensure that the following properties are set for the Registry Serices application as required: Option oslc.registry.context oslc.registry.host oslc.registry.port Description The context root for the Registry Serices application. The default alue is oslc. The fully qualified host name or IP address on which the Registry Serices application is deployed. The default alue is localhost if Registry Serices and Administration Serices are deployed on the same application serer. The listening port for the Registry Serices application. The default alue can be: 9443 if Registry Serices application is deployed to its own WebSphere Application Serer profile if all Serices are installed and deployed on the same application serer and the protocol is HTTPS Chapter 6. Configuring Administration Serices 55

66 Option oslc.registry.protocol Description The protocol to connect to the Registry Serices application. The default alue is HTTPS. 5. Ensure that the following properties are set for Administration Serices as required: Option oslc.sericeproider.context oslc.sericeproider.host oslc.sericeproider.port oslc.sericeproider.protocol Description The context root for Administration Serices. The default alue is admin. The fully qualified host name or IP address on which Administration Serices is deployed. The default alue is localhost. The listening port for Administration Serices. The default alue can be: 9080 if Administration Serices is deployed to its own WebSphere Application Serer profile if all Serices are installed and deployed on the same application serer and the protocol is HTTPS The protocol to connect to Administration Serices. The default alue is HTTPS. Administration Serices properties The Admin_Home/etc/ConfigSericeProider/conf/sericeProider.properties file contains the properties for the Administration Serices client, administration serice proider, and the properties to connect to the Registry Serices application serer. Administration Serices client properties client.log.file= path/config_client_log_file.log The path and file name for the Administration Serices client log file. The default alue is the./logs/configclient.log file in the ADMIN_HOME directory. client.log.leel= Jaa_log_leel The trace leel for the Administration Serices client messages and errors that are logged to the log file. The default is the INFO leel. The alid alues are: INFO WARNING SEVERE FINE FINER FINEST ALL client.tasktable.width= table_width The width of the task table that is displayed in the command window. The default width is 80 characters. The minimum width is 15 characters. client.timeformat= date_format time_format The date and time formats for the Administration Serices client, such that all dates and times are displayed in the specified date and time formats. The default alue is the MM-dd-yyyy HH\:mm\:SSS formats. 56 Jazz for Serice Management: Configuration Guide Draft

67 Registry Serices application properties oslc.registry.context= context_root The context root for the Registry Serices application. The default alue is oslc. oslc.registry.host= host_name The host name or IP address on which the Registry Serices application is deployed. The default alue is localhost if the Registry Serices and Administration Serices applications are deployed on the same application serer. oslc.registry.port= port_number The listening port for the Registry Serices application. The default alue can be: 9443 if Registry Serices application is deployed to its own WebSphere Application Serer profile if all Serices are installed and deployed on the same application serer and the protocol is HTTPS oslc.registry.protocol= HTTP HTTPS The protocol to connect to the Registry Serices application. The default alue is HTTPS. Administration serice proider properties oslc.sericeproider.context= context_root The context root for administration serice proider. The default alue is FAS. oslc.sericeproider.host= host_name The host name or IP address on which administration serice proider is deployed. The default alue is localhost. oslc.sericeproider.port= port_number The listening port for administration serice proider. The default alue can be: 9080 if Administration Serices is deployed to its own WebSphere Application Serer full profile 8080 if Administration Serices is deployed to its own WebSphere Liberty profile if all Serices are installed and deployed on the same application serer and the protocol is HTTPS oslc.sericeproider.protocol= HTTP HTTPS The protocol to connect to Administration Serices administration serice proider. The default alue is HTTPS. Administration Serices command-line interface The adminserices command-line interface runs the Administration Serices client so that you can register or unregister the administration serice proider and managed resources. You can also deploy, iew, update, delete, or run tasks in task bundles. Syntax adminserices.bat sh -operation_name [operation_alue] [-option_name option_alue] Chapter 6. Configuring Administration Serices 57

68 Administration serice proider operations You can use these operations to register or unregister the administration serice proider. -register -register operation on page 29 -unregister -unregister operation on page 30 Managed resources operations You can use these operations to register or unregister the managed resources of the administration serice proider. -registerresource [response_file_path] -registerresource operation on page 29 -unregisterresource resource_id -unregisterresource operation on page 30 -iewresources resource_id -iewresources operation on page 31 Task and task bundle operations You can use these operations to deploy, iew, update, delete, or run tasks in task bundles. -deletetasks task_id -filter filter_alue -deletetasks operation on page 31 -installtasks task_bundle_path[-filter filter_alue][-parameters response_file_path] -installtasks operation on page 32 -runtasks task_id -filter filter_alue -runtasks operation on page 32 -iewtasks [task_id][ -filter filter_alue] -iewtasks operation on page 32 -iewtaskdetails task_id -iewtaskdetails operation on page 33 Other operations These operations proide general information. -buildinfo -buildinfo operation on page 33 -help -help operation on page 33 Filter options -filter filter_alue -filter option on page Jazz for Serice Management: Configuration Guide Draft

69 Security options Use these options with the supported operation. -ltpa token_id -ltpa operation on page 34 -ltpa2 token_id -ltpa2 operation on page 35 -username user_id -password password -username and -password options on page 34 -register operation The -register operation registers the Administration Serices administration serice proider in the proider registry. adminserices -register If basic authentication is enabled for Administration Serices, the user ID and password must be proided to successfully register the administration serice proider. The user ID must be preiously mapped to the PlatformAdministrator administrator role for Administration Serices. adminserices -register -username user_id -password password When the administration serice proider is registered, the following message is displayed in the command line: The administrator serice proider is registered and it is aailable at myserer.companydomain.com is the fully qualified host name of the serer on which Registry Serices application is installed. adminserices_proider_id is the unique identifier for the administration serice proider. -registerresource operation The -registerresource operation registers the specified resource with the administration serice proider. Each resource is registered in the resource registry. It has the following ariants: Registers the resource: adminserices -registerresource When you run the operation without a alue, you can interactiely specify the details for the resource that is based on properties outlined in Table 4 on page 29. Table 15. Resource details Property ersion name identifier DependsOnURLs description Description Resource ersion Unique resource name Unique identifier for the resource Dependencies for the resource Description for the resource Chapter 6. Configuring Administration Serices 59

70 Table 15. Resource details (continued) Property adminsericestype Description Type of serice management system that the resource represents, with the following alid options: 1 ITM 2 Omnibus 3 TCR 4 DASH 5 FRS 6 Other (user_defined_serice_type) Registers the resource by the fully qualified path and response file, as specified by response_file_path alue, that contains the properties as outlined in Table 4 on page 29: adminserices -registerresource response_file_path For example, the operation registers Tioli Common Reporting, as defined by the tcr.response file. The serice management system type is TCR: adminserices.bat -registerresource c:/program Files/IBM/JazzSM/ar/admin_task_bundles/tcr.response Note: Administration Serices proides sample response files in the JazzSM_HOME/ar/admin_task_bundles directory that you can use as reference. -unregister operation The -unregister operation unregisters the Administration Serices administration serice proider from the proider registry and its resources from the resource registry. adminserices -unregister If basic authentication is enabled for Administration Serices, the user ID and password must be proided to successfully unregister the administration serice proider. The user ID must be preiously mapped to the PlatformAdministrator administrator role for Administration Serices. adminserices -unregister -username user_id -password password When the administration serice proider is unregistered, the following message is displayed in the command line: The administration serice proider and its resources hae been unregistered. -unregisterresource operation The -unregisterresource operation unregisters the managed resource, as specified by the resource_id, from the administration serice proider, and deletes the resource from the resource registry. adminserices -unregisterresource resource_id If basic authentication is enabled for Administration Serices, the user ID and password must be proided to successfully unregister the administration serice 60 Jazz for Serice Management: Configuration Guide Draft

71 proider. The user ID must be preiously mapped to the PlatformAdministrator administrator role for Administration Serices. adminserices -unregisterresource resource_id -username user_id -password password When the managed resource is unregistered, the following message is displayed in the command line: The resource has been unregistered. -iewresources operation The -iewresources operation displays one or more resources that are registered with the administration serice proiders. If basic authentication is enabled for Administration Serices, the user ID and password must be proided to iew registered resources. The user ID must be preiously mapped to the PlatformAdministrator administrator role for Administration Serices. It has following ariants: Displays all resources that are registered with the administration serice proider: adminserices -iewresources Displays the registered resource as specified by the resource_id alue: adminserices -iewresources resource_id Table 5 on page 31 summarizes the output for the -iewresources operation. Table 16. iewresources output Column name Product Version Status Description The cell contains: Identifier: The unique identifier for the resource. Name: The name of the resource. Description: The description of the resource. The ersion of the resource. The status of the resource at the specified date and time. -deletetasks operation The -deletetasks operation deletes one or more tasks. You must confirm deletion. It has the following ariants: Deletes the registered task as specified by the task ID alue: adminserices -deletetasks task_id Deletes one or many tasks as specified by the filter_alue filter alue: adminserices -deletetasks -filter filter_alue When the task is deleted, the following message is displayed in the command line: Task task_id deleted successfully. Chapter 6. Configuring Administration Serices 61

72 -installtasks operation The -installtasks operation deploys one or more tasks in the task bundle to the Administration Serices application serer. Each task is registered in the resource registry. It has the following ariants: Deploys all tasks in a task bundle. adminserices -installtasks task_bundle_path For example: adminserices -installtasks c:\tmp\csp\mgmtsys\taskbundle\task_bundle.zip Deploys all tasks in a task bundle with the static parameters either specified interactiely or silently by using the response file as specified by response_file_path alue. adminserices -installtasks task_bundle_path -parameters [response_file_path] For example: adminserices -installtasks c:\tmp\csp\mgmtsys\taskbundle\task_bundle.zip -parameters c:\tmp\csp\mgmtsys\taskparameters.response The task parameters response file specifies static parameters as name-alue pairs. Updates the registered tasks as specified by the filter alue with new ersions of the tasks in the specified task bundle. When you update a task bundle, the Administration Serices client first deletes the old ersion of the tasks in the task bundle and then installs the new ersions. adminserices -installtasks task_bundle_path -filter filter_alue For example: adminserices -installtasks c:\tmp\csp\mgmtsys\taskbundle\task_bundle.zip -filter taskid For each task installed, the following messages are displayed in the command line: Installing task task_id on the admin/admin/serices/tasks/collection. serer. Task task_id Installed successfully. myserer.companydomain.com:port is the fully qualified host name and port of the serer on which Administration Serices is installed. -runtasks operation The -runtasks operation runs one or more tasks. It has the following ariants: Runs the registered task as specified by the task_id alue: adminserices -runtasks task_id Runs the set of registered tasks as specified by the filter_alue filter alue: adminserices -runtasks -filter filter_alue -iewtasks operation The -iewtasks operation displays one or more tasks. It has following ariants: Displays the registered tasks of the administration serice proider. adminserices -iewtasks Displays the registered task as specified by the task_id alue: adminserices -iewtasks task_id Displays one or more registered tasks as specified by the filter_alue filter alue: adminserices -iewtasks -filter filter_alue 62 Jazz for Serice Management: Configuration Guide Draft

73 Table 6 on page 33 summarizes the output for the -iewtasks operation for each task. Table 17. iewtasks output Column name Task Product Status Description The cell contains: Identifier: The unique identifier for the task. Name: The name of the task. The name of the managed resource that is associated with the task. The status of the task at the specified date and time. -iewtaskdetails operation The -iewtasksdetails operation displays the details of the registered task as specified by the task_id alue. adminserices -iewtaskdetails task_id Table 7 on page 33 summarizes the output for the -iewtaskdetails operation for each task. Table 18. iewtasksdetails output Details Task Status Name Description Product Execution time Description The unique identifier for the task. The status of the task at the specified date and time. The name of task. The description for the task. The name of the managed resource that is associated with the task. The last date and time on which the task was last run. -help operation The -help operation displays the help for the Administration Serices CLI in the command window. adminserices -help -buildinfo operation The -buildinfo operation displays the build information for the Administration Serices CLI and administration serice proider in the command window. adminserices -buildinfo If basic authentication is enabled for Administration Serices, the user ID and password must be proided to successfully unregister the administration serice proider. The user ID must be preiously mapped to the PlatformAdministratorRole administrator role for Administration Serices. Chapter 6. Configuring Administration Serices 63

74 adminserices -buildinfo -username user_id -password password The following information is displayed in the command line: The following build information has been retrieed: Client: client_build_number Administration serice proider: configuration_serice_proider_build_number -filter option The -filter option proides filter criteria for the specified operation. A filter can hae one or many filter alues, with each new filter alue joined to the filter expression by using a logical AND operator. -filter filter_alue [filter_alue] Table 8 on page 34 summarizes the filter options and alid alues that are delimited by a colon. Table 19. Filter options Filter option identifier: name: description: target: Value Task identifier Task name Task description Type of serice management system that the resource represents, with the following alid options: ITM Omnibus TCR DASH FRS user_defined_serice_type The following example returns all tasks that hae derby in their task identifiers: adminserices -iewtasks -filter identifier:derby -username and -password options The -username and -password options allow authentication for secure access to Administration Serices, so the specified user_id can run the adminserices command and its operations if that user has sufficient priileges. -username user_id -password password -ltpa operation The -ltpa operation specifies the LTPA Version 1 token as specified by the token_id alue for single sign-on. If both ersion 1 and 2 tokens are specified, precedence is gien to the more secure LTPA2 ersion. adminserices -register -ltpa token_id 64 Jazz for Serice Management: Configuration Guide Draft

75 -ltpa2 operation The -ltpa2 operation specifies the LTPA Version 2 token as specified by the token_id alue for single sign on. If both ersion 1 and 2 tokens are specified, precedence is gien to the more secure LTPA2 ersion. adminserices -register -ltpa2 token_id Administration serice proider The administration serice proider is an Administration Serices component that integrates with Registry Serices to register serice management systems as resources. It also manages data about the configuration tasks that are associated with these managed resources. Administration Serices exposes the administration serice proider as an OSLC serice proider and registers it as a serice proider in the proider registry. The administration serice proider is deployed to the Administration Serices application serer and proides the following features by using RESTful serices: Ability to manually register and unregister the administration serice proider in the proider registry Ability to register and unregister resources of the administration serice proider in the resource registry Ability to install configuration tasks for resources in the resource registry Ability to run the registered tasks for the associated resources Registering the administration serice proider You can register the administration serice proider in the proider registry by using the Administration Serices CLI register operation. Before you begin Ensure that the properties used by the Administration Serices CLI are set and that authentication mechanism is configured. Procedure 1. Open a command window and browse to ADMIN_HOME/bin. 2. Run the adminserices CLI with the -register operation for your operating system as follows: Option On Windows systems On Linux systems Description adminserices.bat -register./adminserices.sh -register If basic authentication is enabled for Administration Serices, the user ID and password must be proided to successfully register the administration serice proider. The user ID must be preiously mapped to the PlatformAdministrator administrator role for Administration Serices. 3. Enter the user name and then the password. The Administration Serices client returns the URI for the administration serice proider when it is successfully registered in the proider registry. Chapter 6. Configuring Administration Serices 65

76 Unregistering the administration serice proider You can unregister the administration serice proider from the proider registry and delete its managed resources from the resource registry by using the Administration Serices CLI unregister operation. Before you begin Ensure that the properties used by the Administration Serices CLI are set and that authentication mechanism is configured. Procedure 1. Open a command window and browse to ADMIN_HOME/bin. 2. Run the adminserices CLI with the -unregister operation for your operating system as follows: Option On Windows systems On Linux systems Description adminserices.bat -unregister./adminserices.sh -unregister If basic authentication is enabled for Administration Serices, the user ID and password must be proided to successfully register the administration serice proider. The user ID must be preiously mapped to the PlatformAdministrator administrator role for Administration Serices. 3. Enter the user name and then the password. The Administration Serices client returns a message that the administration serice proider and its managed resources are successfully unregistered. Managed resources of the administration serice proider You can register resources with the administration serice proider by using the Administration Serices client. A managed resource is also known as a managed system. When you register a resource with the administration serice proider, Administration Serices creates a registration record in the resource registry to register the resource that the administration serice proider manages. When you register multiple resources and if the name and identifier of these resources are the same, they are reconciled as a single resource; hence, they appear only once on the Administration Serices UI. Howeer, you can execute the tasks from all administration serice proiders. Registering resources interactiely You can interactiely register the resources that are managed by the administration serice proider by using the Administration Serices CLI registerresource operation. The Administration Serices client prompts you for the resource details. Before you begin Ensure that the properties used by the Administration Serices CLI are set and that the authentication mechanism is configured. Procedure 1. Open a command window and browse to ADMIN_HOME/bin. 66 Jazz for Serice Management: Configuration Guide Draft

77 2. Run the adminserices CLI for your operating system with the -registerresource operation. Option On Windows systems On Linux systems Description adminserices.bat -registerresource./adminserices.sh -registerresource 3. When prompted, enter the following details: Prompt Resource identifier Resource name Resource description Resource dependencies Valid alues All characters except space, comma, and quotes. String, for example, Tioli Common Reporting String, for example, Reporting system Empty or one or many resources that are separated by a comma Resource ersion String, for example, Serice type Integer in the range of 1 to number, with the following alid options: 1 ITM 2 Omnibus 3 TCR 4 DASH 5 FRS 6 Other Note: Select Other to add custom or user-defined serice type. The Administration Serices client updates the new serice type in the SericeType property of the AdministrableResource.input file. This alue can be used when you register the serice management system as a resource and when you specify the target for the task bundle. 4. When authentication is enabled for the Administration Serices, you must specify a user name with appropriate priileges and the associated password. Note: This user must be mapped to either the PlatformOperator or PlatformAdministrator Administration Serices roles. The Administration Serices client returns the URI for the resource when it is successfully registered with the administration serice proider. Related reference: Administration Serices command-line interface The adminserices command-line interface runs the Administration Serices client so that you can register or unregister the administration serice proider and managed resources. You can also deploy, iew, update, delete, or run tasks in task bundles. Chapter 6. Configuring Administration Serices 67

78 Registering resources silently You can silently register the resources that are managed by the administration serice proider by using the Administration Serices CLI registerresource operation. The Administration Serices client uses a resource registration response file to register the resource. Before you begin Ensure that the properties used by the Administration Serices CLI are set and that the authentication mechanism is configured. Procedure 1. Open a command window and browse to ADMIN_HOME/bin. 2. Create a resource registration response file, with a file extension of.response and sae it to a directory, for example, c:/taskbundleresponse 3. Run the adminserices CLI for your operating system with the -registerresource operation, and specify the name of the resource registration response file. Option On Windows systems Description adminserices.bat -registerresource response_file_path [-username user_id -password password] For example: adminserices.bat -registerresource c:/taskbundleresponse/tcr.response On Linux and AIX systems./adminserices.sh -registerresource response_file_path [-username user_id -password password] For example:./adminserices.sh -registerresource /opt/taskbundleresponse/tcr.response When authentication is enabled for Administration Serices, you must specify a user name with appropriate priileges and the associated password. Use the -username and -password options in the command line; otherwise, you are prompted for them. This user must be mapped to either the PlatformOperator or PlatformAdministrator Administration Serices roles. The Administration Serices client returns a message to state that resource with the specified unique ID in the response file is created. Related reference: Administration Serices command-line interface The adminserices command-line interface runs the Administration Serices client so that you can register or unregister the administration serice proider and managed resources. You can also deploy, iew, update, delete, or run tasks in task bundles. Resource registration response file Use a response file to register a resource that is managed by the administration serice proider in the resource registry. 68 Jazz for Serice Management: Configuration Guide Draft

79 Adding custom serice types You can add custom or user-defined serice types to represent the serice management systems in your integrated serice management enironment in the AdministrableResource.input file. About this task When a serice management system is registered as a managed resource of the serice proider for Administration Serices, the registration includes specifying the type of serice management system. The serice types maps the task bundle to the managed resource, also known as the managed system. Administration Serices currently supports the following predefined serice types: ITM, representing a monitoring management system type Omnibus, representing an operations management system type TCR, representing as the reporting management system type DASH, representing a UI management system type FRS, representing a linked data management system type These serice types are defined in thesericetype property in the AdministrableResource.input file, with each type delimited by using the pipe symbol: SericeType={ITM Omnibus TCR DASH FRS}+ You can define custom serice types to represent the serice management systems in your integrated serice management enironment; howeer, you must ensure that you use this alue when you register the serice management system as a resource and when you specify the target for the task bundle. Procedure 1. Browse to the ADMIN_HOME/etc/ConfigSericeProider/templates directory. 2. Open the AdministrableResource.input file in a text editor. 3. Edit the alue for the SericeType property to specify the user-defined serice type. Add the alue in between the curly braces that are separated by pipe ' '. SericeType={ITM Omnibus TCR DASH FRS}+ For example, to specify a custom serice type for business serice management system, enter: SericeType={ITM Omnibus TCR DASH FRS BSM}+ 4. Sae the file. Resource registration response file Use a response file to register a resource that is managed by the administration serice proider in the resource registry. Create a resource registration response file, with a file extension of.response and sae it to a directory, for example, c:/taskbundleresponse. Table 20. Properties in the resource registration response file Property ersion name Description Resource ersion Unique resource name Chapter 6. Configuring Administration Serices 69

80 Table 20. Properties in the resource registration response file (continued) Property identifier DependsOnURLs description SericeType Description Unique identifier for the resource Dependencies for the resource Description for the resource Type of serice management system that the resource represents, with the following alid options: 1 ITM 2 Omnibus 3 TCR 4 DASH 5 FRS number user_defined_serice_type Examples This example shows the content of the TCR.response file. When you run the Administration Serices client with the -registerresource operation and this file, it registers the IBM Tioli Common Reporting resource in the resource registry. SericeType=TCR identifier=20 description=tioli Common Reporting proides an integrated reporting solution for the products in the Tioli portfolio. TCR allows to link multiple reports across arious Tioli products to simplify the report naigation and accelerate access to key reporting information. name=ibm Tioli Common Reporting ersion=3.1 DependsOnURLs= Note: To use a DBCS locale like Japanese, Chinese or Korean, the DBCS locale-specific content in the response file must be in the Unicode format. Response file in a Unicode format: SericeType=ITM identifier=128 description=\u00e3\ufffd\u201c\u00e3\u201a\u0152\u00e3\ufffd \u00af\u00e3\u20ac\ufffd\u00e6\u2014\u00a5\u00e6\u0153\u00ac \u00e3\ufffd\u00ae\u00e8\u00a3\u00bd\u00e5\u201c\ufffd\u00e3 \ufffd\u00a7\u00e3\ufffd\u2122 name=jp\u00e8\u00a3\u00bd\u00e5\u201c\ufffd ersion=2.1 DependsOnURLs= Rehosting the Registry Serices Before you rehost or moe the Registry Serices, you must perform certain steps to ensure that the Administration Serices work well with the new Registry Serices configuration. Procedure 1. Stop the Administration Serices UI and all the administration serice proiders. 70 Jazz for Serice Management: Configuration Guide Draft

81 Tasks and task bundles 2. Rehost Registry Serices by updating the new registry configuration in the adminsericeshui.properties and sericeproider.properties files. 3. Start all the administration serice proiders. 4. Start the Administration Serices UI. A task is a small program or script that can run independently to perform an operation on a managed system. A task bundle is a plug-in that contains the configuration tasks. The tasks in the task bundle are deployed to Administration Serices. You can use the Administration Serices client to deploy tasks in a task bundle, update tasks, and delete tasks. You can also use it to iew and run tasks; alternatiely, you can use the Administration Serices UI to iew and run them. Related concepts: Tasks A task is a small program or script that can run independently to perform an action on the managed system, for example, check the optimal heap size for the managed system. Each task might require parameters to be entered before it is run. Task bundles A task bundle is a plug-in that contains the configuration tasks that can be performed on the managed systems. The tasks in the task bundle are deployed to Administration Serices. Administration Serices proides task bundles for the following serice management systems: Registry Serices, Dashboard Application Serices Hub, and Tioli Common Reporting. These task bundles contain configuration tasks that can be used for actiities such as modifying configuration settings and monitoring the system health of serice management systems. When you install Administration Serices with Registry Serices, Dashboard Application Serices Hub, or Tioli Common Reporting, Administration Serices registers these serice management systems as managed resources and deploys the respectie task bundle. The registered resources that are also known as managed systems are displayed in the Applications iew of the Administration Serices UI. When you select a managed system in the Applications iew, the tasks that are associated with the managed system are displayed in the Administration Tasks iew. Each task is associated a help; when you select a task in the Administration Tasks iew, the task help is displayed in the Help tab of the Administration Task Details iew. Tasks A task is a small program or script that can run independently to perform an action on the managed system, for example, check the optimal heap size for the managed system. Each task might require parameters to be entered before it is run. You can use the Administration Serices UI or the Administration Serices command-line interface to deploy a task bundle that contains tasks for a managed system. It is also used to update tasks if new ersions are aailable. Alternatiely, you can use Manage Tasks in the Administration Tasks iew to deploy and update task bundles that contain tasks, and delete tasks for a managed system. Manage Tasks is a self-management task that is proided by Administration Chapter 6. Configuring Administration Serices 71

82 Serices for all managed system. This task is isible in the Administration Tasks iew after you register managed systems with the administration serice proider. You can use the Administration Serices UI or Administration Serices command-line interface to iew these tasks. Table 10 on page 42 summarizes the details about each task that can be displayed: in the table in the Administration Tasks iew in the pop-up window, when you hoer oer any cell in the table of the Administration Tasks iew in the Administration Task Details iew, when you select the task in the table of the Administration Tasks iew in the command window, when you run the iewtaskdetails or iewtasks operations with the Administration Serices command-line interface Table 21. Task details Attribute Description Name The display name for the task. Status The status of the task, such as OK or Running. Product The name of the associated managed system. Last updated The date and time on which the task status was last updated or the task action was run. Version The ersion of the task. Description The description of the task. Administration Task Details iew or iewtaskdetails operation only Product The name of the associated managed system. Product ersion The ersion of the managed system. Target The product on which the task is performed. Name The display name for the task. Version The ersion of the task. Description The description of the task. Last updated The date and time on which the task status was last updated or the task action was run. Task Status Details The description of the task status. Task Message details The details of the task execution. You can use the Administration Serices UI or Administration Serices command-line interface and run these tasks to erify the configuration of the managed system or configure the managed system, as follows: Use the Actions > Run Automation or Actions > Run Health Check menu items after you select the tasks in the Administration Tasks iew Use the runtasks operation with the Administration Serices command-line interface Deploying task bundles from the command line You can deploy tasks in the task bundle by using the Administration Serices CLI installtasks operation. 72 Jazz for Serice Management: Configuration Guide Draft

83 Before you begin Ensure that you configure the Administration Serices client before you deploy any task bundles. Procedure 1. Open a command window and browse to ADMIN_HOME/bin. 2. Run the adminserices CLI for your operating system with the -installtasks operation, and specify the fully qualified path and file name for the task bundle. The task bundle might require that you specify static parameters when you deploy the task bundle by using the -installtasks option. You specify them either interactiely or silently by using the response file, as specified the response_file_path alue. Option On Windows systems Description adminserices.bat -installtasks task_bundle_path [-parameters response_file_path] For example, the alue for task_bundle_path is c:\\tmp\\csp\\mgmtsys\\taskbundle\\ task_bundle.zip and c:\\tmp\\csp\\ mgmtsys\\taskparameters.response is the response_file_path alue. On Linux systems./adminserices.sh -installtasks task_bundle_path [-parameters response_file_path] Where the alue for task_bundle_path is for example: \tmp\csp\mgmtsys\taskbundle\ task_bundle.zip For example, the alue for task_bundle_path is /tmp/csp/mgmtsys/task_bundle.zip and /tmp/csp/mgmtsys/taskparameters.response is the response_file_path alue. Note: If you did not specify the task parameter response file, you are prompted for the alues for the static parameters. 3. When authentication is enabled for Administration Serices, you must specify a user name with appropriate priileges and the associated password. Note: This user must be mapped to either the PlatformConfigurator or PlatformAdministrator Administration Serices roles. Updating tasks from the command line You can update deployed tasks by using the Administration Serices CLI installtasks operation. It updates the set of tasks from the specified task bundle. About this task When you update a task, the Administration Serices client first deletes the old ersion of the task and then installs the new ersion. Chapter 6. Configuring Administration Serices 73

84 Procedure 1. Open a command window and browse to ADMIN_HOME/bin. 2. Run the adminserices CLI for your operating system with the -installtasks operation, and specify the fully qualified path and file name for the task bundle and the filter. Option On Windows systems Description adminserices.bat -installtasks task_bundle_path -filter filter_alue Where the alue for task_bundle_path is for example: c:\\tmp\\csp\\mgmtsys\\ taskbundle\\task_bundle.zip and the alue for filter_alue is, for example, identifier:derby. On Linux systems./adminserices.sh -installtasks task_bundle_path -filter filter_alue Where the alue for task_bundle_path is for example: \tmp\csp\mgmtsys\taskbundle\ task_bundle.zip and the alue for filter_alue is, for example, identifier:derby. 3. When authentication is enabled for Administration Serices, you must specify a user name with appropriate priileges and the associated password. Note: This user must be mapped to either the PlatformConfigurator or PlatformAdministrator Administration Serices roles. Deleting tasks from the command line You can delete tasks by using the Administration Serices CLI deletetasks operation. The Administration Serices client can delete a single task or multiple tasks that are based on the specified filter. Procedure 1. Open a command window and browse to ADMIN_HOME/bin. 2. Run the adminserices CLI for your operating system with the -deletetasks operation. Option Description On Windows systems Delete a single task that is based on the task identifier: adminserices.bat -deletetasks task_id Where the task_id alue is, for example, TCR-derby-logging-leel-check. Delete one or many tasks that are based on the filter alue: adminserices.bat -deletetasks -filter filter_alue Where the filter_alue alue is, for example, identifier:derby. 74 Jazz for Serice Management: Configuration Guide Draft

85 Option Description On Linux systems Delete a single task that is based on the task identifier:./adminserices.sh -deletetasks task_id Where the task_id alue is, for example, TCR-derby-logging-leel-check. Delete one or many tasks that are based on the filter alue:./adminserices.sh -deletetasks -filter filter_alue Where the filter_alue alue is, for example, identifier:derby. 3. When authentication is enabled for Administration Serices, you must specify a user name with appropriate priileges and the associated password. Note: This user must be mapped to either the PlatformConfigurator or PlatformAdministrator Administration Serices roles. Configuring the connection to the Registry Serices application You can update the connection properties that Administration Serices UI uses to connect to the Registry Serices application, if there are any changes for this serer in your enironment, for example a new application serer for the Registry Serices application. About this task The connection properties to the Registry Serices application serer are set when you first install Administration Serices UI. Procedure 1. Browse to the ADMINUI_HOME/etc/AdminSericesGUI/conf directory. 2. Open the adminsericesgui.properties file. 3. Set the following properties for the Registry Serices application serer as required: Option registry.context registry.host registry.port Description The context root for the Registry Serices application. The host name or IP address on which the Registry Serices application is deployed. The default alue is localhost if the Registry Serices and Administration Serices UI applications are deployed on the same application serer. The listening port for the Registry Serices application. The default alue is 9443 or if all Serices are installed and deployed on the same application serer and the protocol is HTTPS. Chapter 6. Configuring Administration Serices 75

86 Option registry.protocol Description The protocol to connect to the Registry Serices application. The default alue is HTTPS. Administration Serices UI properties The ADMINUI_HOME>/etc/AdminSericesGUI/conf/adminsericesgui.properties file contains the properties that Administration Serices UI uses to connect to the Registry Serices application serer. registry.context= context_root The context root for the Registry Serices application. The default alue is FRS. registry.host= host_name The host name or IP address on which the Registry Serices application is deployed. The default alue is localhost if the Registry Serices and Administration Serices UI applications are deployed on the same application serer. registry.port= port_number The listening port for the Registry Serices application. The default alue is 9443 or if all Serices are installed and deployed on the same application serer and the protocol is HTTPS. registry.protocol= HTTP HTTPS The protocol to connect to the Registry Serices application. The default alue is HTTPS. Administration Serices Base Edition Fix Pack 1 The Administration Serices Base Edition is a Administration Serices package that proides the command-line interface to work with Administration Serices tasks. Choose the Administration Serices Base Edition package if you want to ealuate the features that are proided by Administration Serices. The Administration Serices Base Edition command-line interface proides capabilities similar to that of the Administration Serices client, except that you cannot run administrator serice proider and managed resource operations. You can perform task and task bundle operations without registering resources with the administration serice proider. When you install Administration Serices, Installation Manager installs the Administration Serices Base Edition package AdminSericesBaseEdition_buildnumber.zip into the JazzSM_HOME/admin/tools directory. Related tasks: Administration Serices Base Edition command-line interface on page 49 You can use the Administration Serices Base Edition command-line interface to perform task and task bundle operations including deploy, iew, update, delete, and run tasks in task bundles. Related reference: 76 Jazz for Serice Management: Configuration Guide Draft

87 Task and task bundle operations on page 47 Administration Serices Base Edition supports the following task and task bundle operations. You can run these operations without registering resources with the administration serice proider. Task and task bundle operations Fix Pack 1 Administration Serices Base Edition supports the following task and task bundle operations. You can run these operations without registering resources with the administration serice proider. Syntax adminserices.bat sh -operation_name -installtasks operation The -installtasks operation deploys one or more tasks in the task bundle to the Administration Serices application serer. Each task is registered in the resource registry. It has the following ariants: Deploys all tasks in a task bundle. adminserices -installtasks task_bundle_path For example: adminserices -installtasks c:\tmp\csp\mgmtsys\taskbundle\task_bundle.zip Deploys all tasks in a task bundle with the static parameters either specified interactiely or silently by using the response file as specified by response_file_path alue. adminserices -installtasks task_bundle_path -parameters [response_file_path] For example: adminserices -installtasks c:\tmp\csp\mgmtsys\taskbundle\task_bundle.zip -parameters c:\tmp\csp\mgmtsys\taskparameters.response The task parameters response file specifies static parameters as name-alue pairs. Updates the registered tasks as specified by the filter alue with new ersions of the tasks in the specified task bundle. When you update a task bundle, the Administration Serices client first deletes the old ersion of the tasks in the task bundle and then installs the new ersions. adminserices -installtasks task_bundle_path -filter filter_alue For example: adminserices -installtasks c:\tmp\csp\mgmtsys\taskbundle\task_bundle.zip -filter taskid For each task installed, the following messages are displayed in the command line: Installing task task_id on the admin/admin/serices/tasks/collection. serer. Task task_id Installed successfully. myserer.companydomain.com:port is the fully qualified host name and port of the serer on which Administration Serices is installed. Chapter 6. Configuring Administration Serices 77

88 -iewtasks operation The -iewtasks operation displays one or more tasks. It has following ariants: Displays the registered tasks of the administration serice proider. adminserices -iewtasks Displays the registered task as specified by the task_id alue: adminserices -iewtasks task_id Displays one or more registered tasks as specified by the filter_alue filter alue: adminserices -iewtasks -filter filter_alue Table 11 on page 48 summarizes the output for the -iewtasks operation for each task. Table 22. iewtasks output Column name Task Product Status Description The cell contains: Identifier: The unique identifier for the task. Name: The name of the task. The name of the managed resource that is associated with the task. The status of the task at the specified date and time. -iewtaskdetails operation The -iewtasksdetails operation displays the details of the registered task as specified by the task_id alue. adminserices -iewtaskdetails task_id Table 12 on page 48 summarizes the output for the -iewtaskdetails operation for each task. Table 23. iewtasksdetails output Details Task Status Name Description Product Execution time Description The unique identifier for the task. The status of the task at the specified date and time. The name of task. The description for the task. The name of the managed resource that is associated with the task. The last date and time on which the task was last run. -runtasks operation The -runtasks operation runs one or more tasks. It has the following ariants: Runs the registered task as specified by the task_id alue: adminserices -runtasks task_id 78 Jazz for Serice Management: Configuration Guide Draft

89 Runs the set of registered tasks as specified by the filter_alue filter alue: adminserices -runtasks -filter filter_alue -deletetasks operation The -deletetasks operation deletes one or more tasks. You must confirm deletion. It has the following ariants: Deletes the registered task as specified by the task ID alue: adminserices -deletetasks task_id Deletes one or many tasks as specified by the filter_alue filter alue: adminserices -deletetasks -filter filter_alue When the task is deleted, the following message is displayed in the command line: Task task_id deleted successfully. Related concepts: Deploying task bundles from the command line on page 42 You can deploy tasks in the task bundle by using the Administration Serices CLI installtasks operation. Related tasks: Updating tasks from the command line on page 43 You can update deployed tasks by using the Administration Serices CLI installtasks operation. It updates the set of tasks from the specified task bundle. Deleting tasks from the command line on page 44 You can delete tasks by using the Administration Serices CLI deletetasks operation. The Administration Serices client can delete a single task or multiple tasks that are based on the specified filter. Administration Serices Base Edition command-line interface Fix Pack 1 You can use the Administration Serices Base Edition command-line interface to perform task and task bundle operations including deploy, iew, update, delete, and run tasks in task bundles. Before you begin Copy the AdminSericesBaseEdition_buildnumber.zip package to the system where you want to use it, and extract the contents of the package into a temporary directory. Procedure 1. Open a command window and browse to tmp_dir/bin. 2. Set the JAVA_HOME enironment ariable for your operating system in the setsericeen.bat sh file and run this modified file. Note: If you hae the JAVA_HOME enironment ariable that is specified as a system enironment ariable, you do not need to run the setsericeen.bat sh file. 3. Run the Administration Serices Base Edition CLI for your operating system with the required operation. Chapter 6. Configuring Administration Serices 79

90 Option On Windows systems On Linux systems Description adminserices.bat -operation_name adminserices.sh -operation_name Related concepts: Deploying task bundles from the command line on page 42 You can deploy tasks in the task bundle by using the Administration Serices CLI installtasks operation. Related tasks: Updating tasks from the command line on page 43 You can update deployed tasks by using the Administration Serices CLI installtasks operation. It updates the set of tasks from the specified task bundle. Deleting tasks from the command line on page 44 You can delete tasks by using the Administration Serices CLI deletetasks operation. The Administration Serices client can delete a single task or multiple tasks that are based on the specified filter. 80 Jazz for Serice Management: Configuration Guide Draft

91 Chapter 7. Configuring Dashboard Application Serices Hub You can perform additional configuration tasks depending on the size of your enterprise, your security policies, and whether you want to share data outside the Dashboard Application Serices Hub enironment. Load balancing for Dashboard Application Serices Hub You can set up a load balanced cluster of console nodes with identical configurations to eenly distribute user sessions. Load balancing is ideal for Dashboard Application Serices Hub installations with a large user population. When a node within a cluster fails, new user sessions are directed to other actie nodes. You can create a load balanced cluster from an existing stand-alone Jazz for Serice Management application serer instance, but must export its data before you configure it for load balancing. The exported data is later imported to one of the nodes in the cluster so that it is replicated across the other nodes in the cluster. Work load is distributed by session, not by request. If a node in the cluster fails, users who are in session with that node must log back in to access the Dashboard Application Serices Hub. Any unsaed work is not recoered. Restriction: Running multiple WebSphere Application Serer profiles on computers configured for Dashboard Application Serices Hub load balancing is not supported. Restriction: Before installing a fix pack in a load balanced enironment, you must remoe all nodes from the load balanced cluster. For details of remoing nodes, see Remoing a node on page 102. After remoing all nodes from the cluster, you must install the fix pack on each node so that they are at the same release leel of Dashboard Application Serices Hub. You can recreate the load balanced cluster after updating each node. Synchronized data After load balancing is set up, changes in the console are stored in global repositories. These changes are synchronized to all of the nodes in the cluster using a common database. The following actions cause changes to the global repositories used by the console. Most of these changes are caused by actions in the Settings folder in the console naigation. Creating, restoring, editing, or deleting a dashboard. Creating, restoring, editing, or deleting a iew. Creating, editing, or deleting a preference profile or deploying preference profiles from the command line. Copying a widget entity or deleting a widget copy. Changing access to a widget entity, dashboard, external URL, or iew. Creating, editing, or deleting a role. Changes to widget preferences or defaults. Copyright IBM Corp. 2012,

92 Changes from the Users and Groups applications, including assigning users and groups to roles. Note: Global repositories should neer be updated manually. During normal operation within a cluster, updates that require synchronization are first committed to the database. At the same time, the node that submits the update for the global repositories notifies all other nodes in the cluster about the change. As the nodes are notified, they get the updates from the database and commit the change to the local configuration. If data fails to be committed on a node, a warning message is logged in the log file. The node is preented from making its own updates to the database. Restarting the Jazz for Serice Management application serer instance on the node rectifies most synchronization issues, if not, the node must be remoed from the cluster for correctie action. For more information, see Monitoring a load balancing cluster on page 101. Note: If the database serer restarts, all connections from it to the cluster are lost. It can take up to 5 minutes for connections to be restored, before users can again perform updates, for example, modifying dashboards. Manual synchronization and maintenance mode Updates to deploy, redeploy, or remoe console modules are not automatically synchronized within the cluster. These changes must be performed manually at each node. For deployment and redeployment operations, the console module package must be identical at each node. When one of the deployment commands is started on the first node, the system enters maintenance mode and changes to the global repositories are locked. After you finish the deployment changes on each of the nodes, the system returns to an unlocked state. There is not any restriction to the order that modules are deployed, remoed, or redeployed on each of the nodes. While in maintenance mode, any attempts to make changes in the console that affect the global repositories are preented and an error message is returned. The only changes to global repositories that are allowed are changes to a user's personal widget preferences. Any changes outside the control of the console, for example, a form submission in a widget to a remote application, are processed normally. The following operations are also not synchronized within the cluster and must be carried out manually for each node. These updates do not place the cluster in maintenance mode. Deploying, redeploying, and remoing wires and transformations Customization changes to the console user interface (for example, custom images or style sheets) using consoleproperties.xml. To reduce the chance that users establish sessions with nodes that hae different wire and transformation definitions, or user interface customizations, schedule changes to coincide with console module deployments. Requirements The following requirements must be met before load balancing can be enabled: 82 Jazz for Serice Management: Configuration Guide Draft

93 If you create a cluster from a stand-alone instance of Dashboard Application Serices Hub, you must export its data before you configure it for load balancing. When you hae configured the cluster, you can import the data to one of the nodes for it to be replicated across the other nodes. Lightweight Directory Access Protocol (LDAP) must be installed and configured as the user repository for each node in the cluster. For information about which LDAP serers you can use, see List of supported software for WebSphere Application Serer V8.5. See Configuring LDAP user registries for instructions on how to enable LDAP for each node. A front-end Network Dispatcher (for example, IBM HTTP Serer) must be set up to handle and distribute all incoming session requests. For more information about this task, see Setting up intermediary serices. DB2 Version 10.1 must be installed within the network to synchronize the global repositories for the console cluster. Each node in the cluster must be enabled to use the same LDAP with the same user and group configuration. All console nodes in load balancing cluster must be installed in the same cell name. After console installation on each node, use the -cellname parameter on the manageprofiles command. All console nodes in load balancing cluster must hae synchronized clocks. The WebSphere Application Serer and Jazz for Serice Management application serer ersions must hae the same release leel, including any fix packs. Fixes and upgrades for the run time must be applied manually at each node. Before joining nodes to a cluster, make sure each node uses the same file-based repository user ID, which is assigned the role of iscadmins. Related tasks: Preparing the HTTP serer for load balancing on page 92 Install the IBM HTTP Serer and configure the Web serer plug-in for passing requests to the Jazz for Serice Management application serer that are part of the load balancing configuration. Installing the IBM HTTP Serer Installing the IBM HTTP Serer Creating a new key database Creating a new key database Creating a self-signed certificate Creating a self-signed certificate Setting up SSL for IBM HTTP Serer Setting up SSL for IBM HTTP Serer Related reference: IBM DB2 Database for Linux, UNIX, and Windows Information Center Consult the IBM DB2 Database Information Center to learn more about installation requirements and how to use DB2. Exporting data from a stand-alone serer to prepare for load balancing You can export data from an existing stand-alone Jazz for Serice Management application serer instance to create a data file that can be imported to a load balanced cluster. Chapter 7. Configuring Dashboard Application Serices Hub 83

94 About this task When you are creating a new load balanced cluster, you must first export all data from the stand-alone instance and subsequently import the preiously exported data once the cluster is set up. Note: If you are joining the serer to an existing cluster, the other nodes in the cluster should not contain custom data, that is, each node in the cluster should be clean installations. When you import data from the stand-alone serer it is replicated across all other nodes. Procedure 1. At the command line, change to the following directory: DASH_HOME/bin/ 2. Run the following command to export the stand-alone serer's data: Linux UNIX restcli.sh export -username console_admin_user_id -password console_admin_password -destination data_file Windows restcli.bat export -username console_admin_user_id -password console_admin_password -destination data_file Where: console_admin_user_id Specifies the administrator user ID. console_admin_password Specifies the password associated with the administrator user ID. data_file Specifies the path and file name for the exported data, for example, c:/tmp/data.zip. 3. Create a new load balanced cluster using the stand-alone serer, or join it to an existing cluster. 4. Import the preiously exported data to any node in the cluster. a. At the command line, if necessary, change to the following directory: DASH_HOME/bin/ b. On one of the nodes in the cluster, run the following command to import the stand-alone serer's data: restcli.sh import -username console_admin_user_id -password console_admin_password -source data_file Where: console_admin_user_id Specifies the administrator user ID. console_admin_password Specifies the password associated with the administrator user ID. data_file Specifies the path and file name for the data to be imported, for example, c:/tmp/data.zip. Results Create a new load balanced cluster using the stand-alone Jazz for Serice Management application serer, or join it to an existing cluster. Once the cluster is configured, you can import the data file to one of the nodes in the cluster. 84 Jazz for Serice Management: Configuration Guide Draft

95 Setting up a load balanced cluster You can configure a Jazz for Serice Management application serer instance to use a database as a file repository instead of a local directory. Before you begin If you are create a cluster from an existing Jazz for Serice Management application serer instance that contains custom data, ensure that you export its data before you begin to configure it for load balancing. When it is configured, you can import the data to one of the nodes in the new cluster. Note: Exporting data from a Tioli Integrated Portal load balanced cluster directly to a Dashboard Application Serices Hub cluster is not supported. You must migrate your Tioli Integrated Portal enironment to a Dashboard Application Serices Hub enironment and then enable load balancing in the new enironment. Dashboard Application Serices Hub is installed on a computer using the cell name that is designated for all console nodes within the cluster. You installed and set up a Network Dispatcher (for example, IBM HTTP Serer), DB2, and an LDAP as explained in Requirements on page 82. Procedure 1. On the computer where DB2 is installed, create a DB2 database (see Creating databases). Note: Load balanced Dashboard Application Serices Hub clusters cannot share a database instance with load balanced Tioli Integrated Portal clusters. The database name for a load balanced cluster is maintained in DASH_HOME/bin/ha/tipha.properties under DBName. The extract from tipha.properties shows the Dashboard Application Serices Hub implementation haing a database name of dashdb. ################################################################### # Database name for TIP HA # Example: DBName=dashdb # DBName=dashdb 2. Check that you hae the JDBC drier for DB2 on the computer where Dashboard Application Serices Hub is installed. The JDBC drier is aailable at: JazzSM_HOME/lib/db2. 3. From a command prompt, change to the DASH_HOME/bin/ha directory and edit the settings in tipha.properties. Property name DBHost DBPort DBName DBProiderClass Description The host name or IP address of the computer where the DB2 database is installed. Example: tipdb.cn.ibm.com Port number of the DB2 serer. Example: (default) The name of the database that you created. Example: dashdb Class name of the DB2 proider. Important: Value: com.ibm.db2.jcc.db2drier - Do not edit this alue. Chapter 7. Configuring Dashboard Application Serices Hub 85

96 Property name DBProiderName DBDatasource DBDatasourceName DBHelperClassName DBDsImplClassName DBDrierVarName DBJDBCDrierPath DBDrierType DBType JaasAliaseName JaasAliasDesc LocalHost LocalPort WasRoot TipHome ProfilePath ProfileName Description Name of the DB2 proider. Important: Value: TIP_Uniersal_JDBC_Drier - Do not edit this alue. JNDI name of the data source. Important: Always use jdbc/tipds. Name of the data source used for load balancing. Important: Always use tipds. DB2 Helper class name. Important: Value: com.ibm.websphere.rsadapter. DB2UniersalDataStoreHelper - Do not edit this alue. DB2 data source implementation class name. Important: Value: com.ibm.db2.jcc.db2connectionpooldatasource - Do not edit this alue. WebSphere enironment ariable name for DB2 JDBC drier class path. Important: Value: TIP_JDBC_DRIVER_PATH - Do not edit this alue. Location of DB2 JDBC drier libraries (for example, db2jcc.jar). Example: JazzSM_HOME/lib/db2 JDBC drier type. Important: Value: 4 - Do not edit this alue. Database type. Important: Value: DB2 - Do not edit this alue. JAAS alias name that is used to store database user name and password. Important: Value: TIPAlias - Do not edit this alue. Description for JAAS alias name. Important: Value: JAAS Alias used for High Aailability - Do not edit this alue. The host name or IP address of the computer on which the console is running. LocalHost and LocalPort uniquely identify the node in the cluster. Example: tip01.cn.ibm.com Administratie console secure port. LocalHost and LocalPort uniquely identify the node in the cluster. Example: The full system path to where the WebSphere Application Serer instance, or embedded WebSphere Application Serer instance, which is associated with the Dashboard Application Serices Hub is installed. Example: C:/IBM/WebSphere/AppSerer The full system path to where the Dashboard Application Serices Hub is installed, that is, DASH_HOME. The full system path to where the WebSphere Application Serer profile for the Dashboard Application Serices Hub is located. The profile may be located within DASH_HOME or WAS_HOME. The profile name that was specified on the manageprofiles command after installation. If no profile name was specified, the default is used. Example: JazzSMProfile 86 Jazz for Serice Management: Configuration Guide Draft

97 Property name CellName NodeName SererName IscAppName Description The cell name that was specified on the manageprofiles command after installation. If no cell name was specified, the default is used. Example: JazzSMNodeCellThis parameter is optional for a single node console installation. For a load balancing cluster, all nodes must use the same cell name. The Jazz for Serice Management application serer node name. Example: JazzSMNode The WebSphere Application Serer instance name. Important: Always use serer1. The Jazz for Serice Management application serer enterprise application name. The Jazz for Serice Management application serer enterprise application is installed in directory the following directory: ${WAS_ROOT}\profiles\${ProfileName}\installedApps\ ${CellName}\${IscAppName}.ear Important: Value: isc - Do not edit this alue. LoggerLeel HAEnabled The leel of logging. The default is OFF. Example: FINER Indicates whether or not load balancing is enabled. Attention: Do not edit this alue manually. 4. Stop the serer. 5. Make sure that your database is empty and the serer is not started. Problems occur if you try to setup load balancing on a non-empty database or actie serer. 6. From a command prompt, change to the WAS_HOME/bin/ha directory and issue this command: Linux UNIX WAS_HOME/bin/ws_ant.sh -f install.ant configha -Dusername=DB2_username -Dpassword=DB2_password -DWAS_username=WAS_admin_username -DWAS_password=WAS_admin_password Windows WAS_HOME\bin\ws_ant.bat -f install.ant configha -Dusername=DB2_username -Dpassword=DB2_password -DWAS_username=WAS_admin_username -DWAS_password=WAS_admin_password 7. Start the serer. Results The load balancing cluster is created and the console node is joined to the cluster as the first node. What to do next Add (or join) extra nodes to the cluster. Joining a node to a load balancing cluster You can configure a Jazz for Serice Management application serer to join an existing load balancing cluster. Chapter 7. Configuring Dashboard Application Serices Hub 87

98 Before you begin 1. If you are joining a stand-alone Jazz for Serice Management application serer instance to a cluster, ensure that you first export all of its data. Once you hae joined it to the cluster, you can then import the preiously exported data. Other nodes in the cluster should not contain any custom data and should effectiely be new installed instances. 2. Make sure you hae successfully enabled load balancing following the steps in Setting up a load balanced cluster on page Dashboard Application Serices Hub should be installed to the node using the same cell name that is designated for the cluster. 4. All console modules deployed to the cluster must be already deployed to the node that you intend to join. 5. You should deploy any wires or transformations used by the nodes in the cluster. 6. If the cluster is using any customization changes in consoleproperties.xml you must copy these changes and this file to the same location on the node that you intend to join. 7. The node must be configured to the same LDAP with the same user and group definitions as all other nodes in the cluster. About this task The following parameters are used on the join option when a node is added: -Dusername - specify the DB2 administrator's username -Dpassword - specify the DB2 administrator's password -DWAS_username - specify the WebSphere Application Serer administrator's username -DWAS_password - specify the WebSphere Application Serer administrator's password Procedure 1. Check that you hae the JDBC drier for DB2 on the computer where Dashboard Application Serices Hub is installed. The JDBC drier is aailable at: JazzSM_HOME/lib/db2. 2. From a command prompt, change to the DASH_HOME/bin/ha directory and edit the settings in tipha.properties. Property name DBHost DBPort DBName DBProiderClass DBProiderName Description The host name or IP address of the computer where the DB2 database is installed. Example: tipdb.cn.ibm.com Port number of the DB2 serer. Example: (default) The name of the database that you created. Example: dashdb Class name of the DB2 proider. Important: Value: com.ibm.db2.jcc.db2drier - Do not edit this alue. Name of the DB2 proider. Important: Value: TIP_Uniersal_JDBC_Drier - Do not edit this alue. 88 Jazz for Serice Management: Configuration Guide Draft

99 Property name DBDatasource DBDatasourceName DBHelperClassName DBDsImplClassName DBDrierVarName DBJDBCDrierPath DBDrierType DBType JaasAliaseName JaasAliasDesc LocalHost LocalPort WasRoot TipHome ProfilePath ProfileName CellName Description JNDI name of the data source. Important: Always use jdbc/tipds. Name of the data source used for load balancing. Important: Always use tipds. DB2 Helper class name. Important: Value: com.ibm.websphere.rsadapter. DB2UniersalDataStoreHelper - Do not edit this alue. DB2 data source implementation class name. Important: Value: com.ibm.db2.jcc.db2connectionpooldatasource - Do not edit this alue. WebSphere enironment ariable name for DB2 JDBC drier class path. Important: Value: TIP_JDBC_DRIVER_PATH - Do not edit this alue. Location of DB2 JDBC drier libraries (for example, db2jcc.jar). Example: JazzSM_HOME/lib/db2 JDBC drier type. Important: Value: 4 - Do not edit this alue. Database type. Important: Value: DB2 - Do not edit this alue. JAAS alias name that is used to store database user name and password. Important: Value: TIPAlias - Do not edit this alue. Description for JAAS alias name. Important: Value: JAAS Alias used for High Aailability - Do not edit this alue. The host name or IP address of the computer on which the console is running. LocalHost and LocalPort uniquely identify the node in the cluster. Example: tip01.cn.ibm.com Administratie console secure port. LocalHost and LocalPort uniquely identify the node in the cluster. Example: The full system path to where the WebSphere Application Serer instance, or embedded WebSphere Application Serer instance, which is associated with the Dashboard Application Serices Hub is installed. Example: C:/IBM/WebSphere/AppSerer The full system path to where the Dashboard Application Serices Hub is installed, that is, DASH_HOME. The full system path to where the WebSphere Application Serer profile for the Dashboard Application Serices Hub is located. The profile may be located within DASH_HOME or WAS_HOME. The profile name that was specified on the manageprofiles command after installation. If no profile name was specified, the default is used. Example: JazzSMProfile The cell name that was specified on the manageprofiles command after installation. If no cell name was specified, the default is used. Example: JazzSMNodeCellThis parameter is optional for a single node console installation. For a load balancing cluster, all nodes must use the same cell name. Chapter 7. Configuring Dashboard Application Serices Hub 89

100 Property name NodeName SererName IscAppName Description The Jazz for Serice Management application serer node name. Example: JazzSMNode The WebSphere Application Serer instance name. Important: Always use serer1. The Jazz for Serice Management application serer enterprise application name. The Jazz for Serice Management application serer enterprise application is installed in directory the following directory: ${WAS_ROOT}\profiles\${ProfileName}\installedApps\ ${CellName}\${IscAppName}.ear Important: Value: isc - Do not edit this alue. LoggerLeel HAEnabled The leel of logging. The default is OFF. Example: FINER Indicates whether or not load balancing is enabled. Attention: Do not edit this alue manually. 3. Stop the serer. 4. Make sure the Jazz for Serice Management application serer is not started. 5. At a command prompt, change to the JazzSM_WAS_Profile/bin directory and issue this command Linux UNIX JazzSM_WAS_Profile/bin/ws_ant.sh -f install.ant configha -Dusername=DB2_username -Dpassword=DB2_password -DWAS_username=WAS_admin_username -DWAS_password=WAS_admin_password Windows JazzSM_WAS_Profile\bin\ws_ant.bat -f install.ant configha -Dusername=DB2_admin_username -Dpassword=DB2_admin_password -DWAS_username=WAS_admin_username -DWAS_password=WAS_admin_password 6. Start the serer. Results The console node is joined to the cluster. What to do next Add another node to the cluster, or if you hae completed adding nodes, enable serer to serer trust for each node to eery other node in the cluster. Depending on the network dispatcher (for example, IBM HTTP Serer) that you use, you might hae further updates to get session requests routed to the new node. Refer to the documentation applicable to your network dispatcher for more information. Enabling serer-to-serer trust Use this procedure to enable load balanced nodes to connect to each other and send notifications. About this task These steps are required to enable load balancing between the participating nodes. Complete these steps on each node. 90 Jazz for Serice Management: Configuration Guide Draft

101 Procedure 1. In a text editor, open the ssl.client.props file from the JazzSM_WAS_Profile/ properties directory. 2. Uncomment the section that starts with com.ibm.ssl.alias=anothersslsettings so that it looks like this: com.ibm.ssl.alias=anothersslsettings com.ibm.ssl.protocol=ssl_tls com.ibm.ssl.securityleel=high com.ibm.ssl.trustmanager=ibmx509 com.ibm.ssl.keymanager=ibmx509 com.ibm.ssl.contextproider=ibmjsse2 com.ibm.ssl.enablesignerexchangeprompt=true #com.ibm.ssl.keystoreclientalias=default #com.ibm.ssl.customtrustmanagers= #com.ibm.ssl.customkeymanager= #com.ibm.ssl.dynamicselectioninfo= #com.ibm.ssl.enabledciphersuites= 3. Uncomment the section that starts with com.ibm.ssl.truststorename=anothertruststore so that it looks like this: # TrustStore information com.ibm.ssl.truststorename=anothertruststore com.ibm.ssl.truststore=${user.root}/config/cells/tipcell/nodes/tipnode/trust.p12 com.ibm.ssl.truststorepassword={xor}cdo9hgw= com.ibm.ssl.truststoretype=pkcs12 com.ibm.ssl.truststoreproider=ibmjce com.ibm.ssl.truststorefilebased=true com.ibm.ssl.truststorereadonly=false 4. Update the location of the trust store that the signer should be added to in the com.ibm.ssl.truststore property of AnotherTrustStore by replacing the default alue com.ibm.ssl.truststore=${user.root}/etc/trust.p12 with the correct path for your trust store. Example: com.ibm.ssl.truststore=${user.root}/config/cells/tipcell/nodes/tipnode02 /trust.p12 After the update, the section must look like this: com.ibm.ssl.truststorename=anothertruststore com.ibm.ssl.truststore=${user.root}/config/cells/tipcell/nodes/tipnode/trust.p12 com.ibm.ssl.truststorepassword={xor}cdo9hgw= com.ibm.ssl.truststoretype=pkcs12 com.ibm.ssl.truststoreproider=ibmjce com.ibm.ssl.truststorefilebased=true 5. Sae your changes to ssl.client.props. 6. Stop and restart the serer. 7. Complete all of the steps so far on each node before you continue with the rest of the steps. 8. Run the following command on each node for each myremotehost (that is, for eery node that you want to enable trust with) in the cluster: Windows JazzSM_WAS_Profile\bin\retrieeSigners.bat NodeDefaultTrustStore AnotherTrustStore -host myremotehost -port remote_soap_port Linux UNIX JazzSM_WAS_Profile/bin/retrieeSigners.sh NodeDefaultTrustStore AnotherTrustStore -host myremotehost -port remote_soap_port where myremotehost is the name of the computer to enable trust with; remote_soap_port is the SOAP connector port number (16313 is the default). If Chapter 7. Configuring Dashboard Application Serices Hub 91

102 you hae installed with non-default ports, check JazzSM_WAS_Profile/ properties/portdef.props for the alue of SOAP_CONNECTOR_ADDRESS and use that. 9. Stop and restart the serer. Example In this example, the load balancing cluster is comprised of two Microsoft Windows nodes named myserer1 and myserer2. The command entered on myserer1: retrieesigners.bat NodeDefaultTrustStore AnotherTrustStore -host myserer2 -port The command entered on myserer2: retrieesigners.bat NodeDefaultTrustStore AnotherTrustStore -host myserer1 -port Verifying a load balancing implementation Use the information in this topic to erify that your Dashboard Application Serices Hub load balancing setup is working correctly once you hae added all nodes to the cluster and enabled serer-to-serer trust. About this task This task allows you to confirm the following functions are working correctly: The database used for your load balancing cluster is properly created and initialized. Eery node in the cluster uses the database as its repository instead of its own local file system. Serer-to-serer trust is properly enabled between nodes in the cluster. To erify your load balancing configuration: Procedure 1. Ensure that each Jazz for Serice Management application serer instance on eery node in the cluster is running. 2. In a browser, log into one node, create a new View and sae your changes. 3. Log into the remaining nodes and erify that the newly created iew is aailable in each one. Preparing the HTTP serer for load balancing Install the IBM HTTP Serer and configure the Web serer plug-in for passing requests to the Jazz for Serice Management application serer that are part of the load balancing configuration. Before you begin The IBM HTTP Serer uses a web serer plug-in to forward HTTP requests to the Jazz for Serice Management application serer. You can configure the HTTP serer and the web serer plug-in to act as the load balancing serer, that is, pass requests (HTTP or HTTPS) to one of any number of nodes. The load balanced methods that are supported by the plug-in are round robin and random. 92 Jazz for Serice Management: Configuration Guide Draft

103 With a round robin configuration, when a browser connects to the HTTP serer, it is directed to one of the configured nodes. When another browser connects, it is directed to a different node. With the random setting, each browser is connected randomly to a node. When a connection is established between a browser and a particular node, that connection remains until the user logs out or the browser is closed. The HTTP serer is necessary for directing traffic from browsers to the applications that run in the Dashboard Application Serices Hub enironment. The serer is installed between the console and the Jazz for Serice Management application serer, and is outside the firewall. The web serer plug-in uses the plugin-cfg.xml configuration file to determine whether a request is for the Jazz for Serice Management application serer. About this task Complete this procedure to configure the web serer plug-in for load balancing for each node. Procedure 1. If IBM HTTP Serer Version 8.5 is not installed, install it before you proceed. It must be installed where it can be accessed from the Internet or intranet (or both). Note: Fix Pack 1 Jazz for Serice Management bundles the WebSphere Application Serer Version 8.5 Supplements installation media, which contains the installation packages for IBM HTTP Serer and the IBM HTTP Serer plug-in for IBM WebSphere Application Serer. If you do not hae the DVDs, you can download the electronic images for Jazz for Serice Management from IBM Passport Adantage. See Downloading Jazz for Serice Management. 2. Install IBM HTTP Serer ensuring that you include the IBM HTTP Serer Plug-in for IBM WebSphere Application Serer option. For more information, see com.ibm.websphere.ihs.doc/ihs/welc6miginstallihsdist.html. 3. Create a CMS-type key database. For more information, see com.ibm.websphere.ihs.doc/ihs/tihs_createkeydb390.html. 4. Create a self-signed certificate to allow SSL connections between nodes. For more information, see com.ibm.websphere.ihs.doc/ihs/tihs_selfsigned.html. 5. To enable SSL communications for the IBM HTTP Serer, in a text editor, open HTTP_serer_install_dir/conf/httpd.conf. Locate the line # End of example SSL configuration and add the following lines, ensuring that the KeyFile line references the key database file that was created in step 3 and sae your changes. LoadModule ibm_ssl_module modules/mod_ibm_ssl.so Listen 443 <VirtualHost *:443> SSLEnable SSLProtocolDisable SSL2 ErrorLog "C:/Program Files (x86)/ibm/httpserer/logs/sslerror.log" TransferLog "C:/Program Files (x86)/ibm/httpserer/logs/sslaccess.log" Chapter 7. Configuring Dashboard Application Serices Hub 93

104 KeyFile "C:/Program Files (x86)/ibm/websphere/plugins_1/etc/plugin-key.kdb" SSLStashfile "C:/Program Files (x86)/ibm/websphere/plugins_1/etc/plugin-key.sth" </VirtualHost> SSLDisable For more information, see the first example at infocenter/wasinfo/8r5/topic/com.ibm.websphere.ihs.doc/ihs/ tihs_setupssl.html. 6. Restart the IBM HTTP Serer, For more information, see pic.dhe.ibm.com/infocenter/wasinfo/8r5/topic/com.ibm.websphere.ihs.doc/ ihs/tihs_startihs.html. 7. On the IBM HTTP Serer computer, to erify that SSL is enabled ensure that you can access 8. Stop and restart the Jazz for Serice Management application serer: a. In the JazzSM_WAS_Profile/bin directory, depending on your operating system, enter one of the following commands: Windows stopserer.bat serer1 UNIX Linux stopserer.sh serer1 Note: On UNIX and Linux systems, you are prompted to proide an administrator username and password. b. In the JazzSM_WAS_Profile/bin directory, depending on your operating system, enter one of the following commands: Windows startserer.bat serer1 UNIX Linux startserer.sh serer1 9. Start the HTTP serer: a. Change to the directory where it is installed. b. Run this command: bin/apachectl start Note you must restart the serer after you change the plugin-cfg.xml file. What to do next Enter the URL for the HTTP Serer in a browser HTTP_serer_port and it is forwarded to one of the nodes. Note: The default load balancing method is random, whereby each browser is connected randomly to a node. Related tasks: Installing the IBM HTTP Serer Installing the IBM HTTP Serer Creating a new key database Creating a new key database Creating a self-signed certificate Creating a self-signed certificate Setting up SSL for IBM HTTP Serer Setting up SSL for IBM HTTP Serer Related reference: IBM DB2 Database for Linux, UNIX, and Windows Information Center Consult the IBM DB2 Database Information Center to learn more about installation 94 Jazz for Serice Management: Configuration Guide Draft

105 requirements and how to use DB2. Web serer plug-in tuning tips The Web serer works with the application serer to balance workload. Setting clone IDs for nodes Assign a clone ID for all nodes in the cluster. About this task Complete this procedure to set clone IDs for all nodes in the cluster. You must carry out these steps on each node. Procedure 1. In a text editor, open the serer.xml file from the JazzSM_WAS_Profile/config/ cells/jazzsmnode01cell/nodes/jazzsmnode01/serers/serer1 directory 2. In serer.xml, locate the entry <components xmi:type="applicationserer.webcontainer:webcontainer. 3. Within the components element, add the following entry: <properties xmi:id="webcontainer_ " name="httpsessioncloneid" alue="12345" required="false"/> Where: alue is the clone ID for the node, for example, alue="12345". The clone ID must be unique to each node. An example of an updated components element is proided here: <components xmi:type="applicationserer.webcontainer:webcontainer" xmi:id="webcontainer_ " enableserletcaching="false" disablepooling="false"> <statemanagement xmi:id="statemanageable_ " initialstate="start"/> <serices xmi:type="applicationserer.webcontainer:sessionmanager" xmi:id="sessionmanager_ " enable="true" enableurlrewriting="false" enablecookies="true" enablessltracking="false" enableprotocolswitchrewriting="false" sessionpersistencemode="none" enablesecurityintegration="false" allowserializedsessionaccess="false" maxwaittime="5" accesssessionontimeout="true"> <defaultcookiesettings xmi:id="cookie_ " domain="" maximumage="-1" secure="false"/> <sessiondatabasepersistence xmi:id="sessiondatabasepersistence_ " datasourcejndiname="jdbc/ Sessions" userid="db2admin" password="{xor}oz1tpjsynje=" db2rowsize="row_size_4kb" tablespacename=""/> <tuningparams xmi:id="tuningparams_ " usingmultirowschema="false" maxinmemorysessioncount="1000" allowoerflow="true" scheduleinalidation="false" writefrequency="time_based_write" writeinteral="10" writecontents="only_updated_attributes" inalidationtimeout="30"> <inalidationschedule xmi:id="inalidationschedule_ " firsthour="14" secondhour="2"/> </tuningparams> </serices> <properties xmi:id="webcontainer_ " name="httpsessioncloneid" alue="12345" required="false"/> </components> 4. Sae the changes you made to serer.xml. Chapter 7. Configuring Dashboard Application Serices Hub 95

106 Generating the plugin-cfg.xml file Run GenPluginCfg.bat to generate the plugin-cfg.xml file and sae it in JazzSM_WAS_Profile/config/cells. About this task Complete this procedure to generate the plug-cfg.xml file. You must carry out these steps on each node. Important: You must run GenPluginCfg.bat to generate a new plugin-cfg.xml file each time that a dashboard application is installed into a load balanced Jazz for Serice Management application serer enironment. Procedure 1. On a node, change to JazzSM_WAS_Profile/bin/ and run the following command: Windows GenPluginCfg.bat Linux UNIX GenPluginCfg.sh This command generates a file that is named plugin-cfg.xml and saes it to the JazzSM_WAS_Profile/config/cells directory. 2. On the IBM HTTP Serer, in the following directory, replace the existing plugin-cfg.xml with the ersion generated in step 1: HTTP_web_serer_install_dir/plugins/config/webserer1 The following steps establish the new /ibm/* URI (Uniform Resource Identifier), which is where the plug-in redirects requests: a. On the IBM HTTP Serer, change to the directory where the web serer definition file is (such as, cd plugins/config/webserer1). b. Open the plugin-cfg.xml file in a text editor and edit the file to proide details of your IBM HTTP Serer and all Jazz for Serice Management application serer instances. Refer to the sample content proided to assist you in editing plugin-cfg.xml. For more information about the plugin-cfg.xml file, see the reference material at: infocenter/wasinfo/8r5/topic/com.ibm.websphere.nd.doc/ae/ rws_plugincfg.html. Note: Where the proided sample differs from the WebSphere Application Serer reference information, the WebSphere Application Serer takes precedence. HTTP SERVER PATH is the path to where the HTTP serer is installed. HTTP SERVER PORT is the port for the HTTP serer. SERVER1 is the fully qualified name of the computer where the Jazz for Serice Management application serer is installed and started. SERVER2 is the fully qualified name of the computer where another Jazz for Serice Management application serer is installed and started. CLONE_ID is the unique clone ID assigned to a particular node (serer) in the cluster. c. In the SererCluster section, the alue for the keyring property must be HTTP SERVER PATH /plug-ins/etc/plug-in-key.kdb and the alue for the stashfile property must be HTTP SERVER PATH /plug-ins/etc/plug-inkey.sth. 96 Jazz for Serice Management: Configuration Guide Draft

107 d. Continue to add Serer entries for any other nodes, following the same pattern. Add an entry under PrimarySerers for each additional serer. e. Add CloneID and LoadBalanceWeight attributes for eery Serer entry. Important: For more information about the web serer plug-in workload management policies and to help you determine the appropriate alues for the elements LoadBalance and LoadBalanceWeight, see: &uid=swg Attention: The HTTP and HTTPS port alues for all nodes must be the same. While the following extract is from an IBM HTTP Serer Version 7.0 plugin-cfg.xml, its contents are still releant. Some details are changed for IBM HTTP Serer Version 8.5. For more information about the format of the plugin-cfg.xml file in IBM HTTP Serer Version 8.5, see: pic.dhe.ibm.com/infocenter/wasinfo/8r5/topic/ com.ibm.websphere.nd.doc/ae/rws_plugincfg.html <Config ASDisableNagle="false" IISDisableNagle="false" IgnoreDNSFailures="false" RefreshInteral="60" ResponseChunkSize="64" AcceptAllContent="false" IISPluginPriority="High" FIPSEnable="false" AppSererPortPreference="HostHeader" VHostMatchingCompat="false" ChunkedResponse="false"> <Log LogLeel="Trace" Name="HTTP SERVER PATH/Plugins/logs/webserer1/ http_plugin.log"/> <Property Name="ESIEnable" Value="true" /> <Property Name="ESIMaxCacheSize" Value="1024" /> <Property Name="ESIInalidationMonitor" Value="false" /> <Property Name="ESIEnableToPassCookies" Value="false" /> <Property Name="PluginInstallRoot" Value="HTTP SERVER PATH/Plugins" /> <VirtualHostGroup Name="default_host"> <VirtualHost Name="*:16310" /> <VirtualHost Name="*:80" /> <VirtualHost Name="*:16311" /> <VirtualHost Name="*:5060" /> <VirtualHost Name="*:5061" /> <VirtualHost Name="*:443" /> <VirtualHost Name="*:HTTP SERVER PORT"/> </VirtualHostGroup> <SererCluster CloneSeparatorChange="false" GetDWLMTable="false" IgnoreAffinityRequests="true" LoadBalance="Round Robin" Name="serer1_Cluster" PostBufferSize="64" PostSizeLimit="-1" RemoeSpecialHeaders="true" RetryInteral="60"> <Serer Name="TIPNode1_serer1" ConnectTimeout="0" CloneID="CLONE_ID" ExtendedHandshake="false" SererIOTimeout="0" LoadBalanceWeight="100" MaxConnections="-1" WaitForContinue="false"> <Transport Hostname="SERVER1" Port="16310" Protocol="http"/> <Transport Hostname="SERVER1" Port="16311" Protocol="https"> <Property name="keyring" alue="http SERVER PATH\Plugins\config \webserer1\plugin-key.kdb"/> <Property name="stashfile" alue="http SERVER PATH\Plugins\config \webserer1\plugin-key.sth"/> </Transport> </Serer> <Serer Name="TIPNode1_serer2" ConnectTimeout="0" CloneID="CLONE_ID" ExtendedHandshake="false" SererIOTimeout="0" LoadBalanceWeight="100" MaxConnections="-1" Chapter 7. Configuring Dashboard Application Serices Hub 97

108 98 Jazz for Serice Management: Configuration Guide Draft WaitForContinue="false"> <Transport Hostname="SERVER2" Port="16310" Protocol="http"/> <Transport Hostname="SERVER2" Port="16311" Protocol="https"> <Property name="keyring" alue="http SERVER PATH\Plugins\config \webserer1\plugin-key.kdb"/> <Property name="stashfile" alue="http SERVER PATH\Plugins\config \webserer1\plugin-key.sth"/> </Transport> </Serer> <PrimarySerers> <Serer Name="TIPNode1_serer1" /> <Serer Name="TIPNode1_serer2" /> </PrimarySerers> </SererCluster> <UriGroup Name="serer1_Cluster_URIs"> <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/it/*" /> <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/IBM_WS_SYS_RESPONSESERVLET/*" /> <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/IBM_WS_SYS_RESPONSESERVLET/*.jsp" /> <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/IBM_WS_SYS_RESPONSESERVLET/*.js" /> <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/IBM_WS_SYS_RESPONSESERVLET/*.jsw" /> <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/IBM_WS_SYS_RESPONSESERVLET/j_security_check" /> <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/IBM_WS_SYS_RESPONSESERVLET/ibm_security_logout" /> <Uri AffinityCookie="JSESSIONID_ibm_console_16310" AffinityURLIdentifier="jsessionid" Name="/ibm/console/*" /> <Uri AffinityCookie="JSESSIONID_ibm_console_16310" AffinityURLIdentifier="jsessionid" Name="/ibm/help/*" /> <Uri AffinityCookie="JSESSIONID_ibm_console_16310" AffinityURLIdentifier="jsessionid" Name="/ibm/action/*" /> <Uri AffinityCookie="JSESSIONID_ibm_console_16310" AffinityURLIdentifier="jsessionid" Name="/ISCWire/*" /> <Uri AffinityCookie="JSESSIONID_ibm_console_16310" AffinityURLIdentifier="jsessionid" Name="/isc/*" /> <Uri AffinityCookie="JSESSIONID_ibm_console_16310" AffinityURLIdentifier="jsessionid" Name="/ISCHA/*" /> <Uri AffinityCookie="JSESSIONID_ibm_console_16310" AffinityURLIdentifier="jsessionid" Name="/tip_ISCAdminPortlet/*" /> <Uri AffinityCookie="JSESSIONID_ibm_console_16310" AffinityURLIdentifier="jsessionid" Name="/ISCAdminPortlets/*" /> <Uri AffinityCookie="JSESSIONID_ibm_console_16310" AffinityURLIdentifier="jsessionid" Name="/mum/*" /> <Uri AffinityCookie="JSESSIONID_ibm_console_16310" AffinityURLIdentifier="jsessionid" Name="/ibm/TIPChangePasswd/*" /> <Uri AffinityCookie="JSESSIONID_ibm_console_16310" AffinityURLIdentifier="jsessionid" Name="/ibm/TIPExportImport/*" /> <Uri AffinityCookie="JSESSIONID_ibm_console_16310" AffinityURLIdentifier="jsessionid" Name="/ibm/tioli/*" /> <Uri AffinityCookie="JSESSIONID_ibm_console_16310" AffinityURLIdentifier="jsessionid" Name="/proxy/*" /> <Uri AffinityCookie="JSESSIONID_ibm_console_16310" AffinityURLIdentifier="jsessionid" Name="/TIPWebWidget/*" /> <Uri AffinityCookie="JSESSIONID_ibm_console_16310" AffinityURLIdentifier="jsessionid" Name="/ibm/dbfile/*" /> <Uri AffinityCookie="JSESSIONID_ibm_console_16310" AffinityURLIdentifier="jsessionid" Name="/ibm/TIPChartPortlet/*" /> <Uri AffinityCookie="JSESSIONID_ibm_console_16310" AffinityURLIdentifier="jsessionid" Name="/TIPUtilPortlets/*" /> <Uri AffinityCookie="JSESSIONID_ibm_console_16310" AffinityURLIdentifier="jsessionid" Name="/WIMPortlet/*" />

109 <Uri AffinityCookie="JSESSIONID_ibm_console_16310" AffinityURLIdentifier="jsessionid" Name="/SysMgmtCommonTaskGroups/*" /> <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/ibm/tioli/*"/> <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/ibm/console/*"/> <Uri AffinityCookie="JSESSIONID" AffinityURLIdentifier="jsessionid" Name="/ITMOSD/*"/> </UriGroup> <Route SererCluster="serer1_Cluster" UriGroup="serer1_Cluster_URIs" VirtualHostGroup="default_host" /> <RequestMetrics armenabled="false" newbehaior="false" rmenabled="false" traceleel="hops"> <filters enable="false" type="uri"> <filtervalues enable="false" alue="/snoop" /> <filtervalues enable="false" alue="/hitcount" /> </filters> <filters enable="false" type="source_ip"> <filtervalues enable="false" alue=" " /> <filtervalues enable="false" alue=" " /> </filters> <filters enable="false" type="jms"> <filtervalues enable="false" alue="destination=aaa" /> </filters> <filters enable="false" type="web_services"> <filtervalues enable="false" alue="wsdlport=aaa:op=bbb:namespace=ccc" /> </filters> </RequestMetrics> </Config> Configuring SSL from each node to the IBM HTTP Serer For load balanced implementations, you must configure SSL between the IBM HTTP Serer plug-in and each node in the cluster. Before you begin IBM HTTP Serer is installed and configured for load balancing. About this task For each node in the cluster, follow these instructions to configure the node to communicate oer a secure (SSL) channel with the IBM HTTP Serer. Procedure 1. Log in to the Dashboard Application Serices Hub. 2. In the naigation pane, click Console Settings > Websphere Administratie Console and click Launch Websphere administratie console. 3. Follow these steps to extract signer certificate from the truststore: a. In the WebSphere Application Serer administratie console naigation pane, click Security > SSL certificate and key management. b. In the Related Items area, click the Key stores and certificates link and in the table click the NodeDefaultTrustStore link. c. In the Additional Properties area, click the Signer certificates link and in the table that is displayed, select the root entry check box. d. Click Extract and in the page that is displayed, in the File name field, enter a certificate file name (certficate.arm. For example, c:\tipc064ha1.arm. e. From the Data Type list, select the Base64-encoded ASCII data option and click OK. Chapter 7. Configuring Dashboard Application Serices Hub 99

110 f. Locate the extracted signer certificate and copy it to the computer that is running the IBM HTTP Serer. Note: These steps are particular to Dashboard Application Serices Hub, for general WebSphere Application Serer details and further information, see: com.ibm.websphere.base.doc/ae/tsec_sslextractsigncert.html 4. On the computer that is running the IBM HTTP Serer, follow these steps to import the extracted signer certificate into the key database: a. Start the key management utility (ikeyman), if it is not already running, from HTTP_SERVER_PATH/bin: UNIX Linux At the command line, enter./ikeyman.sh Windows At the command prompt, enter ikeyman.exe b. Open the CMS key database file that is specified in plugin-cfg.xml. For example, HTTP_SERVER_PATH/plug-ins/etc/plug-in-key.kdb. c. Proide the password (default is WebAS) for the key database and click OK. d. From the Key database content, select Signer Certificates. e. Click Add and select the signer certificate that you copied from the node to the computer that is running the IBM HTTP Serer and click OK. f. Select the Stash password to a file check box and click OK to sae the key database file. Note: For more information about certificates in WebSphere Application Serer, see com.ibm.websphere.ihs.doc/ihs/tihs_ikeyscca.html. 5. Repeat these steps for each node in the cluster. 6. For the changes to take effect, stop and restart all nodes in the cluster and also restart the computer that is running the IBM HTTP Serer. a. In the JazzSM_WAS_Profile/bin directory, depending on your operating system, enter one of the following commands: Windows stopserer.bat serer1 UNIX Linux stopserer.sh serer1 Note: On UNIX and Linux systems, you are prompted to proide an administrator user name and password. b. In the JazzSM_WAS_Profile/bin directory, depending on your operating system, enter one of the following commands: Windows startserer.bat serer1 UNIX Linux startserer.sh serer1 c. Restart the IBM HTTP Serer. For more information, see com.ibm.websphere.ihs.doc/ihs/tihs_startihs.html. What to do next You can access the load balanced cluster through ibm/console (assuming that the default context root (/ibm/console) was defined in at the time of installation. 100 Jazz for Serice Management: Configuration Guide Draft

111 Importing stand-alone instance data to a cluster If you created a cluster from a stand-alone Jazz for Serice Management application serer instance, you can then import the data that you exported prior to configuring the stand-alone instance as a cluster node. About this task Import the preiously exported data file to any node in the cluster. Important: The instructions in this topic apply only to importing data that was exported when preparing to create a load balanced cluster from a stand-alone Jazz for Serice Management application serer instance, as described in Exporting data from a stand-alone serer to prepare for load balancing on page 83. Procedure 1. At the command line, change to the following directory: DASH_HOME/bin/ 2. On one of the nodes in the cluster (most likely the node that was preiously set up as a stand-alone serer instance), run the following command to import the data file: Linux UNIX restcli.sh import -username console_admin_user_id -password console_admin_password -source data_file Windows restcli.bat import -username console_admin_user_id -password console_admin_password -source data_file Where: console_admin_user_id Specifies the administrator user ID. console_admin_password Specifies the password associated with the administrator user ID. data_file Specifies the path and file name to the data file that is to be imported, for example, c:/tmp/data.zip. Results The data from the initial Jazz for Serice Management application serer is imported to the node and replicated across the other cluster nodes. Monitoring a load balancing cluster If synchronized data fails to be committed to a node in the cluster, remoe that node from the cluster for correctie action. Use the diagnosis tool to identify any unsynchronized nodes in the load balancing cluster. To determine if changes to global data are not committed to any of the nodes, use the HATool command script to check the synchronization of modules and repositories on the nodes in a cluster. For the HATool, you must proide the DB2 administrator's credentials. Query synchronization of modules Use this command to determine if all nodes hae identical sets of modules Chapter 7. Configuring Dashboard Application Serices Hub 101

112 deployed. DASH_HOME/bin/ha/HATool.bat/sh modules username password -bynodes -showall The following parameters are optional. -bynodes Specifies that the results of the command are ordered by the node in the cluster. This parameter is optional. The default is to list the results by module. -showall Specifies that all modules and nodes in the cluster should be returned. This parameter is optional. The default is to return only modules for unsynchronized nodes. Query the synchronization of global repositories Use this command to determine if all repositories are synchronized on all nodes. DASH_HOME/bin/ha/HATool.bat/sh repositories username password -bynodes -showall The following parameters are optional. -bynodes Specifies that the results of the command are ordered by the node in the cluster. This parameter is optional. The default is to list the results by repository. -showall Specifies that all modules and nodes in the cluster should be returned. This parameter is optional. The default is to return only repositories for unsynchronized nodes. Release the global lock Use this command to manually release the global lock placed on all of the console nodes when the cluster is in maintenance mode. This command is used when a node cannot commit a change during synchronization and must be taken offline. DASH_HOME/bin/ha/HATool.bat/sh release-lock username password Remoing a node Follow these steps to remoe a node from the load balancing cluster. About this task The following parameters are used on the disjoin option when a node is remoed. -Dusername - specify the DB2 administrator's username -Dpassword - specify the DB2 administrator's password -DWAS_username - specify the WebSphere Application Serer administrator's username -DWAS_password - specify the WebSphere Application Serer administrator's password Procedure 1. From a command prompt, change to the JazzSM_WAS_Profile/bin/ha directory and issue this command: 102 Jazz for Serice Management: Configuration Guide Draft

113 Linux UNIX JazzSM_WAS_Profile/bin/ws_ant.sh -f uninstall.ant disjoin -DdeleteExistingDataSource=true -Dusername=DB2_username -Dpassword=DB2password -DWAS_username=WAS_admin_username -DWAS_password=WAS_admin_password Windows JazzSM_WAS_Profile\bin\ws_ant.bat -f uninstall.ant disjoin -DdeleteExistingDataSource=true -Dusername=DB2_username -Dpassword=DB2password -DWAS_username=WAS_admin_username -DWAS_password=WAS_admin_password Important: The -DdeleteExistingDataSource argument is mandatory and must be set to true. 2. Update the network dispatcher (for example, IBM HTTP Serer) to remoe the node from the configuration. Remoing a remote node About this task This command should be used only in the rare occasions where physical access to the node is not aailable or a serious hardware or software failure has occurred. If the node is remotely disjoined but continues to function, some problems with synchronization might arise that can lead to problems with data consistency and synchronization. Procedure 1. From a command prompt, change to the JazzSM_WAS_Profile/bin/ha directory and issue this command: Windows..\ws_ant.bat -f uninstall.ant remote-disjoin DremoteHost=remote_host DremotePort=9044 -Dusername=DB2_username -Dpassword=DB2_password Linux UNIX../ws_ant.sh -f uninstall.ant remote-disjoin DremoteHost=remote_host DremotePort=9044 -Dusername=DB2_username -Dpassword=DB2_password 2. Update the network dispatcher (for example, IBM HTTP Serer) to remoe the node from the configuration. Remoing a load balancing cluster Follow these steps to remoe the last node from a cluster and thereby the cluster itself. Before you begin Make sure you hae remoed all other nodes from the cluster. This command should be issued from the last actie node remaining in the cluster. About this task The following parameters are used on the join option when a node is added. -Dusername - specify the DB2 administrator's username -Dpassword - specify the DB2 administrator's password Chapter 7. Configuring Dashboard Application Serices Hub 103

114 Procedure From a command prompt, change to the JazzSM_WAS_Profile/bin/ha directory and issue this command: Windows..\ws_ant.bat -f uninstall.ant uninstall -Dusername=DB2_username -Dpassword=DB2_password Linux UNIX../ws_ant.sh -f uninstall.ant uninstall -Dusername=DB2_username -Dpassword=DB2_password Configuring Tioli Access Manager in Dashboard Application Serices Hub You can configure Dashboard Application Serices Hub to use Tioli Access Manager WebSEAL Version 6.1 to manage authentication. You must install and configure Tioli Access Manager WebSEAL Version 6.1. To set up and configure Tioli Access Manager WebSEAL, see infocenter/tiihelp/2r1/index.jsp?topic=%2fcom.ibm.itame.doc_6.1 %2Fam61_install195.htm. For more information on administering Tioli Access Manager WebSEAL, see am61_webseal_admin.htm. Configuring single sign-on using ETai In a WebSphere Application Serer (WAS) enironment, Tioli Access Manager WebSEAL can be used as a reerse proxy to intercept incoming http or https requests to ensure that users are authenticated and authorized and are passed to the releant Jazz for Serice Management application serer. ETai is the component that implements the WebSphere Application Serer trust association interceptor interface to achiee single sign on from WebSEAL to the Jazz for Serice Management application serer. Dashboard Application Serices Hub supports single sign-on (SSO) with perimeter authentication serices such as reerse proxies through trust associations. When trust associations are enabled, the WebSphere Application Serer is not required to authenticate a user if a request arries from a trusted source that has already performed authentication. Once a trust association is configured between WebSEAL and the Jazz for Serice Management application serer, a user can login into Tioli Access Manager and then access the Jazz for Serice Management application serer without haing to re-authenticate. The ETai must be configured in Jazz for Serice Management application serer serer and is responsible for establishing trust against the WebSEAL serer. ETai simplifies the use of Tioli Access Manager and the configuration required to achiee SSO. One adantage is that Tioli Access Manager and Dashboard Application Serices Hub can use different user registries and still be able to perform SSO. It also proides the mapping between different registry formats. Installing ETai Use these instructions, to install the Tioli Access Manager Extended Trust Association Interceptor in a Dashboard Application Serices Hub enironment. 104 Jazz for Serice Management: Configuration Guide Draft

115 Before you begin Source a copy of com.ibm.sec.authn.tai.etai_6.0.jar from your installation media. About this task To install ETai: Procedure 1. Copy com.ibm.sec.authn.tai.etai_6.0.jar to the plugins directory. 2. At the command line, depending on your operating system, run the releant command: UNIX Linux DASH_HOME/bin/Osgicfginit.sh Windows DASH_HOME\bin\Osgicfginit.bat 3. Copy pd.jar to DASH_HOME/jaa/jre/lib/ext What to do next Configure ETai in a Dashboard Application Serices Hub enironment. Enabling a trust association for ETai You must enable a trust association between the Tioli Access Manager Extended Trust Association Interceptor in the Dashboard Application Serices Hub enironment. About this task To configure a trust association for ETai: Procedure 1. Log in to the console and click Console Settings > WebSphere Administratie Console. 2. In the WebSphere Administratie Console page, click Launch WebSphere administratie console. 3. In the WebSphere Administratie Console naigation pane, click Global security. 4. In the Global security page, expand Web security and click Trust association. 5. In the General Properties area, click the Enable trust association option if it is disabled and click Apply. Your update is saed and you are returned to the Global security page. 6. In the Global security page, expand Web security and click Trust association to display the Trust association page. 7. In the Additional properties area, click the Interceptors link to display the Interceptors page. 8. If com.ibm.sec.authn.tai.tametai is not listed on the page, click New. 9. In the Interceptor class name field enter the string com.ibm.sec.authn.tai.tametai and click Apply. 10. In the Messages area, click the Sae link to commit your change. Chapter 7. Configuring Dashboard Application Serices Hub 105

116 What to do next Configure ETai in the a Dashboard Application Serices Hub enironment. Configuring custom properties for ETai Once you hae enabled a trust association for the Tioli Access Manager Extended Trust Association Interceptor in the Dashboard Application Serices Hub enironment, you must configure its custom properties. About this task To configure custom properties for the ETai: Procedure 1. Log in to the console and click Console Settings > WebSphere Administratie Console. 2. In the WebSphere Administratie Console page, click Launch WebSphere administratie console. 3. In the WebSphere Administratie Console naigation pane, click Global security. 4. In the Global security page, expand Web security and click Trust association to display the Trust association page. 5. In the Additional properties area, click the Interceptors link to display the Interceptors page. 6. From the list of interceptor classes, select the com.ibm.sec.authn.tai.tametai entry. 7. In the Additional properties area, click the Custom properties link to display the Custom properties page. 8. Reiew the details for the custom properties listed in Table 1: Table 24. ETai custom properties Property details Property name: com.ibm.websphere.security.webseal.usewebsphereuserregistry Type: string Required: Yes Notes ETai authenticates the trusted user against the WebSphere Application Serer user registry or the Tioli Access Manager Authorization Serer. If this property is set to true, the resulting Subject will not contain a PDPrincipal as the Tioli Access Manager Authorization Serer is required to build the PDPrincipal. Any other alue for this property will result in a PDPrincipal being added to the Subject. Values: true or false Default alue: true 106 Jazz for Serice Management: Configuration Guide Draft

117 Table 24. ETai custom properties (continued) Property details Notes Property name: com.ibm.websphere.security.webseal.tamuserdnmapping Required: Yes Value: WAS Default alue: TAM Property name: com.ibm.websphere.security.webseal.tamgroupdnmapping Required: Yes Value: WAS Default alue: TAM Property name: com.ibm.websphere.security.webseal.loginid Type: String Required: Yes Value: Default alue: None websealssoid The ETai adds users' credential information into the JAAS Subject. This information includes the users dn. Maps this dn to the WebSphere Application Serer dn, or (Value = WAS). If a mapping is attempted for a user that does not exist in the WebSphere Application Serer user registry, it is ignored and not added to the JAAS Subject. The ETai adds users' credential information into the JAAS Subject. This information includes the group dn's. The ETai can be configured to either: Map these dn's to the WebSphere Application Serer dn's, or (Value = WAS). If a mapping is attempted for a group that does not exist in the WebSphere Application Serer user registry, it is ignored and not added to the JAAS Subject. The alue of this property must exist as a alid user in the user registry. If necessary, create a new user in the Dashboard Application Serices Hub registry called websealssoid. The ETai must be configured with the username of the WebSEAL trusted user. This is the single sign-on user that is authenticated using the password in the Basic Authentication header inserted by WebSEAL in the request. The format of the username is the short name representation. This property interacts with the following property: com.ibm.websphere.security.webseal.usewebsphereuserregistry If com.ibm.websphere.security.webseal.usewebsphereuserregistry is set to true then the specified user must exist in either the WebSphere Application Serer user registry or the Tioli Access Manager user registry. Chapter 7. Configuring Dashboard Application Serices Hub 107

118 Table 24. ETai custom properties (continued) Property details Notes Property name: com.ibm.websphere.security.webseal.checkviaheader Type: String Required: Yes Value: true Default alue: false Property name: com.ibm.websphere.security.webseal.id Required: Yes Value: i-creds Default alue: i-creds Property name: com.ibm.websphere.security.webseal.hostnames Required: Yes Value: A comma separated list of strings. Default alue: There is no default alue for this property. The ETai can be configured so that the Via header can be ignored when alidating trust for a request. This property is required, if WebSEAL is to allow requests into the Dashboard Application Serices Hub only from particular hosts. This property interacts with the following properties: com.ibm.websphere.security.webseal.hostnames com.ibm.websphere.security.webseal.ports If com.ibm.websphere.security.webseal.checkviaheader is set to false then the alues set for the two associated properties are not used. I-creds carries end user credentials, which is used by Dashboard Application Serices Hub for authorization. Note: Any additional alues set for this property are added to a list along with I-creds, that is, I-creds is a required header for the ETai. The ETai can be configured so that the request must arrie from a list of expected hosts. If any of the hosts in the Via header of the HTTP request are not listed in the alues set for this property, the request is ignored by the ETai. This property interacts with the following property: com.ibm.websphere.security.webseal.ports All of the alues listed for com.ibm.websphere.security.webseal.hostnames are used with the ports listed for com.ibm.websphere.security.webseal.ports to indicate a trusted host. For example, if: com.ibm.websphere.security.webseal.hostnames is set to abc,xyz com.ibm.websphere.security.webseal.ports is set to 80,443 Then, the Via header is checked for these hostname/port combinations: abc:80; abc:443; xyz:80; xyz:443. If com.ibm.websphere.security.webseal.checkviaheader is set to false then the alues set for com.ibm.websphere.security.webseal.hostnames are not used. 108 Jazz for Serice Management: Configuration Guide Draft

119 Table 24. ETai custom properties (continued) Property details Property name: com.ibm.websphere.security.webseal.ports Required: Yes Value: 443 Default alue: There is no default alue for this property. Property name: com.ibm.websphere.security.webseal.ssopwdexpiry Required: No Value: Default alue: 600 A positie integer. Property name: com.ibm.websphere.security.webseal.grouprealmprefix Notes This property interacts with the following property: com.ibm.websphere.security.webseal.hostnames All of the alues listed for com.ibm.websphere.security.webseal.hostnames are used with the ports listed for com.ibm.websphere.security.webseal.ports to indicate a trusted host. For more information, see the notes for com.ibm.websphere.security.webseal.hostnames. Once trust has been established for a request, the password for the Single sign-on user is cached for subsequent trust alidation of requests. This saes the ETai from haing to re-authenticate the single sign-on user with the user registry for eery request, therefore increasing performance. The cache timeout period can be modified by setting this property to the required time in seconds. If the password expiry property is set to 0, the cached password does not expire. This property is needed to map the group realm prefix from Tioli Access Manager to group realm prefix in WebSphere Application Serer registry. Required: Yes Value: group: Default alue: 600 Property name: com.ibm.websphere.security.webseal.userrealmprefix This property is needed to map the user realm prefix from Tioli Access Manager to group realm prefix in WebSphere Application Serer registry. Required: Yes Value: user: Default alue: If a custom property does not exist, click New to configure a custom property and proide a name, alue, and optional description and click Apply to add the custom property. 10. If the custom property exists, but is not in line with the details proided in Table 24 on page 106, click on the custom property entry, update its details and click Apply to modify the custom property. 11. Stop and restart the serer. Chapter 7. Configuring Dashboard Application Serices Hub 109

120 What to do next Configure the Tioli Access Manager WebSEAL by creating a WebSEAL junction and creating a junction mapping table. Checking your Tioli Access Manager configuration To ensure that your Tioli Access Manager configuration is alid, you can carry out a number of checks. Before you begin Ensure that you hae the following software ersions installed: Tioli Access Manager Version 6.1 Tioli Integrated Portal Version 1.1 fix pack 11 or later, or Jazz for Serice Management application serer About this task This topic describes how to check the following items: The status of the Tioli Access Manager serer. Connecting to the Jazz for Serice Management application serer. Procedure 1. To check the status of the Tioli Access Manager serer, at the command line, enter pd start status. The following output indicates that the Tioli Access Manager serer is running: pdmgrd yes yes pdacld yes no (sometimes yes) pdmgrproxyd no no webseald-ip1 yes yes 2. To check if the Lightweight Directory Access Protocol (LDAP) user registry is actie: a. At the command line, enter pdadmin -a sec_master -p sec_master_password. Note: This command assumes that pdadmin is in the path. Expected output: pdadmin -a sec_master -p sec_master_password b. At the command line, enter user list * 10. Example output: sec_master imgrd/master iacld/ip1 ip1-webseald/ip1 c. To quit, at the command line, enter quit. 3. If the Tioli Access Manager processes are not started, at the command line enter pd start start. If the processes are already started, the following output can be expected: Starting the: Access Manager authorization serer Could not start the serer 110 Jazz for Serice Management: Configuration Guide Draft

121 4. To check that you can connect from the Jazz for Serice Management application serer to the Tioli Access Manager computer: a. On the Jazz for Serice Management application serer use a Web browser to connect to A security message may be displayed, confirm the Tioli Access Manager self-signed certificate to display an authorization dialog. b. Enter a username and password to display the Tioli Access Manager WebSEAL splash screen (username = sec_master, password = sec_master_password). What to do next Configure the WebSEAL keystore. Configuring the WebSEAL keystore To allow the Jazz for Serice Management application serer to use Tioli Access Manager WebSEAL, you must import Jazz for Serice Management application serer security certificate to the WebSEAL keystore. About this task To export the Jazz for Serice Management application serer security certificate and import it into the WebSEAL keystore: Procedure 1. Log in to the Dashboard Application Serices Hub console. 2. Export the Dashboard Application Serices Hub X.509 certificate. The process for exporting aries depending on your browser. Refer to your browser documentation for assistance. For example, the following substeps describe how you can export the certificate using a Firefox browser: a. Double-click on lock icon in the status bar of browser window to display the Security dialog for the Web page. b. Click View Certificate and in the Certificate Viewer dialog and then click the Details tab. c. Click Export and in the Sae Certificate To File dialog and select a directory to export the Dashboard Application Serices Hub X.509 certificate. 3. Copy the exported certificate file to the Tioli Access Manager computer. 4. On the Tioli Access Manager computer, at the command line, change to the directory that hosts the IKeyman utility. For example, the following directories reflect typical locations for the IKeyman utility, but it may ary depending on your enironment: Linux UNIX WAS_HOME/profiles/profile_name/bin/ Windows WAS_HOME\jaa\jre\bin\ 5. Start the IKeyman utility and complete the substeps: UNIX Linux At the command line, enter./ikeyman.sh Windows At the command line, enter ikeyman.exe a. On the toolbar, click Open to display the Open window. b. Select CMS as the key database type. Chapter 7. Configuring Dashboard Application Serices Hub 111

122 c. Click Browse and from /ar/pdweb/www-ip1/certs, select pdsr.kdb to display the Password Prompt dialog. The default password reflects the file name, that is, pdsr. d. In the Key database content section, select Signer Certificates and click Add. e. In the Add CA's Certificate from a File dialog, for the Data type, select the Base64-encoded ASCII data option and click Browse. f. Locate the Dashboard Application Serices Hub X.509 certificate and enter a label for the certificate (for example, tipmachine). g. Click Sae to add the certificate to the WebSEAL keystore (do not change the certificate's file name). 6. To restart Tioli Access Manager WebSEAL, at the command line, enter pdweb restart. The following is the expected output: Stopping the: webseald-ip1 Starting the: webseald-ip1 What to do next Create a WebSEAL junction. Creating a WebSEAL junction A WebSEAL junction is an HTTP or HTTPS connection between a front-end WebSEAL serer and a back-end Web application serer, for example the Jazz for Serice Management application serer. About this task Junctions logically combine the Web space of the back-end serer with the Web space of the WebSEAL serer, resulting in a unified iew of the entire Web object space. To create a junction: Procedure 1. On the Tioli Access Manager computer, at the command line, enter pdadmin -a sec_master_account -p sec_master_password. 2. At the command line, enter sl. The following is the expected output: iacld-ip1 ip1-webseald-ip1 Note: Where ip1 is the hostname of the Tioli Access Manager computer. 3. Enter s t ip1-webseald-ip1 list. The following is the expected output: / 4. Enter s t ip1-webseald-ip1 create -t ssl -c i-creds -b supply -h DASH_hostname/ip -p DASH_admin_console_secure_port /tip. Where: s t = serer task ip1-webseal-ip1 = WebSEAL instance name -t ssl = transport type is SSL -c i-creds = needed for single sign on (SSO) to work, carry credential of user -b supply = basic authorization header needed for SSO to work 112 Jazz for Serice Management: Configuration Guide Draft

123 The following is the expected output: Created junction at /tip Note: If you want to delete a junction, enter s t ip1-webseald-ip1 delete /tip. Note: If you want to show details for a junction, enter s t ip1-webseald-ip1 show /tip. What to do next Create a WebSEAL junction mapping table. Creating a WebSEAL junction mapping table A junction mapping table maps specific target resources to junction names. Junction mapping is an alternatie to a cookie-based solution for filtering dynamically generated serer-relatie URLs. About this task To create a WebSEAL junction mapping table: Procedure 1. On the Tioli Access Manager computer, in a text editor open the WebSEAL configuration file, /opt/pdweb/etc/webseald-ip1.conf. 2. In the [junction] section, edit the jmt-map path so that it reads jmt-map = lib/jmt.conf. Note: This path is relatie to the serer root path. Check the serer root path in the [serer] section of the file and take a note of the full jmt-map path. For example, /opt/pdweb/www-ip1/lib/jmt.conf. 3. In a text editor create or edit open the jmt.conf file and add or modify the following: /tip /ibm/console/* Note: The /ibm/console/ element of the path shown assumes that the Dashboard Application Serices Hub root context path was not reconfigured at installation time. 4. To load the jmt.conf file into WebSEAL, enter s t ip1-webseald-ip1 jmt load. The following is the expected output: DPWWM1462I JMT Table successfully loaded 5. To restart the WebSEAL serer, enter pdweb restart. The following is the expected output: Stopping the: webseald-ip1 Starting the: webseald-ip1 What to do next Test the WebSEAL junction. Testing the WebSEAL junction Once you hae created a WebSEAL junction, you can test it. Chapter 7. Configuring Dashboard Application Serices Hub 113

124 About this task To test a WebSEAL junction: Procedure 1. In your Web browser's address bar, enter ibm/console, where tip is the name of the WebSEAL junction. The Dashboard Application Serices Hub login page is displayed. 2. To test if Tioli Access Manager challenges you when you try to access the Dashboard Application Serices Hub: a. Close all instances of your Web browser. b. Start your Web browser and go to console/. Note: The /ibm/console/ element of the URL shown assumes that the Dashboard Application Serices Hub root context path was not reconfigured at installation time. If the WebSEAL junction is working as expected, an Authentication Required dialog is displayed and you hae to proide Tioli Access Manager account (sec_master) details to proceed. What to do next Edit customizationproperties.xml to ensure that when you log out of Dashboard Application Serices Hub that you also log out from Tioli Access Manager. Configuring single sign off for Tioli Access Manager and Dashboard Application Serices Hub To ensure that you when you log out from the Dashboard Application Serices Hub that you also log out from Tioli Access Manager, you must edit customizationproperties.xml. About this task To configure single sign off for the Jazz for Serice Management application serer and the Tioli Access Manager computer: Procedure 1. In a text editor, open JazzSM_WAS_Profile/config/cells/JazzSMNode01Cell/ applications/isclite.ear/deployments/isclite/isclite.war/web-inf/ customizationproperties.xml. 2. Edit the TAMJunctionName property, as follows: <consoleproperties:console-property id="tamjunctionname" alue="tip"/> <consoleproperties:console-property id="websealserername" alue=""/> Where: TAMJunctionName is the junction name in Tioli Access Manager that is configured to point at the Jazz for Serice Management application serer. WebSealSererName is a Tioli Access Manager WebSEAL serer instance name. This property allows the Jazz for Serice Management application serer process requests from declared WebSEAL hosts. 114 Jazz for Serice Management: Configuration Guide Draft

125 Results When you log out from the Dashboard Application Serices Hub, a Successful Logout message is displayed in your browser. This indicates that you logged out from both the Dashboard Application Serices Hub and Tioli Access Manager. Setting form-based authentication for WebSEAL Tioli Access Manager proides form-based authentication as an optional alternatie to the standard Basic Authentication mechanism. About this task For information on WebSEAL authentication and changing from basic mode to the form-based mode refer to Tioli Access Manager documentation at com.ibm.itame.doc_6.1/am61_webserers_admin74.htm#chpt4_amwebpi_authent: Configuring access for HTTP and HTTPS By default, the Jazz for Serice Management application serer requires HTTPS (Hypertext Transfer Protocol Secure) access. If you want some users to be able to log in and use the console with no encryption of transferred data, including user ID and password, configure the enironment to support both HTTP and HTTPS modes. Before you begin After installing Dashboard Application Serices Hub and before beginning this procedure, log in to the console to ensure that it has connectiity and can start successfully. About this task Configuring for HTTP and HTTPS console access inoles editing the web.xml file of Web components. Use this procedure to identify and edit the appropriate Web XML files. Procedure 1. Change to the following directory: JazzSM_WAS_Profile/config/cells/ JazzSMNode01Cell/applications. 2. From this location, locate the web.xml files in the following directories: For the Integrated Solutions Console web application archie: isc.ear/deployments/isc/isclite.war/web-inf For the Charts web application archie: isc.ear/deployments/isc/ TIPChartPortlet.war/WEB-INF For the Dashboard Application Serices Hub Change Password web application archie: isc.ear/deployments/isc/tipchangepasswd.war/web- INF 3. Open one of the web.xml files using a text editor. 4. Find the <transport-guarantee> element. The initial alue of all <transport-guarantee> elements is CONFIDENTIAL, meaning that secure access is always required. Chapter 7. Configuring Dashboard Application Serices Hub 115

126 5. Change the setting to NONE to enable both HTTP and HTTPS requests. The element now reads: <transport-guarantee>none</transport-guarantee>. 6. Sae the file, and then repeat these steps for the other web.xml deployment files. 7. Log in to Dashboard Application Serices Hub. 8. In the naigation pane, click Console Settings > Websphere Administratie Console and click Launch Websphere Administratie Console. 9. In the WebSphere Application Serer administratie console, select Security > Global security and click the External authorization proiders link. 10. In the External authorization proiders page, select the Update with application names listed option. 11. In the text pane, type isc and click Apply. 12. In the messages area, click the Sae link to commit your changes to the master configuration. 13. Stop and restart the serer. Example The following example is a section of the web.xml file for TIPChangePasswd where the transport-guarantee parameter is set to NONE: <security-constraint> <display-name> ChangePasswdControllerSerletConstraint</display-name> <web-resource-collection> <web-resource-name>changepasswdcontrollerserlet</web-resource-name> <url-pattern>/*</url-pattern> </web-resource-collection> <auth-constraint> <description>roles</description> <role-name>administrator</role-name> <role-name>operator</role-name> <role-name>configurator</role-name> <role-name>monitor</role-name> <role-name>iscadmins</role-name> </auth-constraint> <user-data-constraint> <transport-guarantee>none</transport-guarantee> </user-data-constraint> </security-constraint> What to do next Users must now specify a different port, depending on the mode of access. The default port numbers are as follows: Use the HTTP port for logging in to the Dashboard Application Serices Hub on the HTTP port. Use the HTTPS secure port for logging in to the Dashboard Application Serices Hub. Note: If you want to use single sign-on (SSO) then you must use the fully qualified domain name of the Dashboard Application Serices Hub host. 116 Jazz for Serice Management: Configuration Guide Draft

127 Configuring the LTPA token timeout alue You can configure the Lightweight Third Party Authentication (LTPA) token timeout alue for Dashboard Application Serices Hub in the WebSphere Application Serer console. Before you begin Dashboard Application Serices Hub is enabled for single sign-on. About this task The default timeout for an LTPA token is 120 minutes. An LTPA timeout causes you to be logged out from Dashboard Application Serices Hub and can also cause an authentication popup message, if the first request after the timeout is an AJAX request from a widget. To configure the LTPA token timeout: Procedure 1. In the Dashboard Application Serices Hub naigation pane, click Console Settings > WebSphere Admin Console. 2. Click Launch WebSphere Admin Console to start the WebSphere Application Serer console. 3. In the WebSphere Application Serer console naigation pane, click Security > Global security. 4. In the Authentication area of the Global security page, click the LTPA link. 5. In the LTPA timeout area of the LTPA page, edit the alue for the LTPA timeout and click OK. 6. In the Messages area of the Global security page, click the Sae link and log out of the WebSphere Application Serer console. What to do next In a load balanced enironment, you must set the LTPA token timeout alue on each of the Jazz for Serice Management application serer instances. Configuring CMS to use a remote database The Context Menu Serice (CMS) is a component of Dashboard Application Serices Hub and it can be configured to use a remote database, which can be used by product to share information outside of the Dashboard Application Serices Hub enironment. CMS facilitates launch-in-context capability between products. The term launch-in-context is used to describe the ability for one application to inoke a function or launch a user interface proided by another application while also passing in data that the function or user interface may immediately process. CMS enables launch-in-context by allowing a product to register launch points for itself and locate launch points for other products. Launch points proide information to allow an application to inoke a function or UI from another application. To configure CMS to use a remote database, you must create a database and then create a data source within Dashboard Application Serices Hub that CMS can use. Chapter 7. Configuring Dashboard Application Serices Hub 117

128 Creating a database for CMS Copy CMS scripts from your Dashboard Application Serices Hub installation to your remote computer and create a database. About this task To create a remote database for CMS: Procedure 1. On the computer running Dashboard Application Serices Hub, at the command line, change to the following directory: DASH_HOME/bin/cms The CMS directory contains a number of scripts that are proided by Dashboard Application Serices Hub. The script that you use depends on the type of database and the operating system of the database computer: Linux UNIX db2_scripts.zip for a DB2 database Linux UNIX MsSql_scripts.zip for a Microsoft SQL Serer database Linux UNIX Oracle_scripts.zip for an Oracle database Windows db2_scripts.tar for a DB2 database Windows MsSql_scripts.tar for a Microsoft SQL Serer database Windows Oracle_scripts.tar for an Oracle database The steps described here reflect setting up a DB2 database on a on a Microsoft Windows system. 2. Transfer a copy of the releant script file from the CMS directory to your remote database computer and take note of the location in which you sae the file. For example, for a DB2 database running on a Microsoft Windows system, you need to transfer a copy of db2_scripts.zip to the remote computer. 3. On the remote database system, extract the file that you copied to a known location and at the command line change to that directory. For example, for a DB2 database: cd C:\demo\db2scripts\db2 4. Open the CMS_database_type_Readme.txt file, in this case CMS_DB2_ReadMe.txt, in a text editor. This file proides instructions and samples on how to use the scripts proided. 5. Open a database command window, so that you can execute database commands. For example, for a DB2 database running on a Windows system, click Start > IBM DB2 > DB2COPY1 (default) > Command Line Tools > Command Window. 6. In the command window, change to the directory that contain your extracted script files. For example, cd demo\db2_scripts\db2 7. Run the database setup command proiding the releant arguments to the parameters outlined in the CMS_database_type_Readme.txt file for the database setup command. For example, run CMS_DB2Setup.bat -d database_name -u database_user_name -p database_user_password. Where: 118 Jazz for Serice Management: Configuration Guide Draft

129 database_name The name of the database that you want to create. You can also proide the name of an existing database. database_user_name The user name for the database. database_user_password The user password associated with the specified user name. The database is now ready to communicate with a Dashboard Application Serices Hub data source. What to do next When you hae set up a remote database, you can configure a data source in Dashboard Application Serices Hub that CMS can use. Deleting a data source definition Before you create a CMS data source, in some circumstance you many want to delete an existing data source definition. About this task To delete a data source: Procedure 1. Run the following command to list existing data sources: $AdminConfig list DataSource ---> get DS name string 2. Run the following command to remoe the data source: $AdminConfig remoe ds_name_string Where ds_name_string is the name of the data source that you want to remoe. 3. Sae your changes: $sae Creating a data source for a remote database Create a CMS datasource on your Dashboard Application Serices Hub instance that a remote database can use. About this task To create a data source: Procedure 1. On the computer running Dashboard Application Serices Hub, at the command line, create a new directory: Linux For example, mkdir JazzSM_WAS_Profile/bin/cms/demo 2. Extract the releant database_type_scripts file from the CMS directory to the new directory. The CMS directory contains a number of scripts that are proided by Dashboard Application Serices Hub. The script that you use depends on the type of database and the operating system of the database computer: Chapter 7. Configuring Dashboard Application Serices Hub 119

130 Linux UNIX db2_scripts.tar for a DB2 database Linux UNIX MsSql_scripts.tar for a Microsoft SQL Serer database Linux UNIX Oracle_scripts.tar for an Oracle database Windows db2_scripts.zip for a DB2 database Windows MsSql_scripts.zip for a Microsoft SQL Serer database Windows Oracle_scripts.zip for an Oracle database Linux For example, if the new directory is located in the CMS directory, run the following command: $ tar -xf../db2_scripts.tar 3. Change directory to the extracted database_type directory (for example, db2) that is created in the directory that you created in 1 on page 119. Linux For example, cd db2/ 4. Open the CMS_database_type_DataSource.txt file, for example, CMS_DB2_DataSource.txt, in a text editor. This file proides instructions on how to set up the data source. 5. Change directory to the location of the wsadmin command. Linux For example, cd JazzSM_WAS_Profile/bin. 6. Run the wsadmin command to create the datasource. Tip: Use the example in the CMS_database_type_DataSource.txt file to assist you with the command syntax. The following is an extract from CMS_DB2_DataSource.txt: Linux./wsadmin.sh -lang jython -user console_user_name -password console_user_password -f path_to_createcmsdatasource_tip.py DASH_HOME/uniersalDrier/lib/db2jcc.jar:DASH_HOME/uniersalDrier/lib/ db2jcc_license_cu.jar database_user_name database_user_password database_name database_hostname database_port_number Windows wsadmin.bat -lang jython -user console_user_name -password console_user_password -f path_to_createcmsdatasource_tip.py DASH_HOME\uniersalDrier\lib\db2jcc.jar;DASH_HOME\uniersalDrier\lib\ db2jcc_license_cu.jar database_user_name database_user_password database_name database_hostname database_port_number Where: jython The script language type. console_user_name The Dashboard Application Serices Hub administrator user name. console_user_password The Dashboard Application Serices Hub administrator user password. path_to_createcmsdatasource_tip.py The file path and name of the createcmsdatasource_tip.py. For example, in Linux./cms/demo/db2/createCMSDataSource_TIP.py. DASH_HOME/uniersalDrier/lib/db2jcc.jar;DASH_HOME/uniersalDrier/ lib/db2jcc_license_cu.jar The file path and name of the database Jar file and license Jar file. 120 Jazz for Serice Management: Configuration Guide Draft

131 Note: The file paths should be separated by a : on Linux systems and by a ; on Windows systems. database_user_name The database user name that you used when you created, or specified the database. database_user_password The password associated with the database user name. database_name The database name that you created, or specified. database_hostname The database hostname or IP address. database_port_number The port number that allows you to communicate with the database. For example, the default DB2 database port number is The data source in Dashboard Application Serices Hub is configured. What to do next When you hae configured the data source in Dashboard Application Serices Hub, you can configure the hostname. Related tasks: Remoing a data source If required you can remoe an existing data source. Remoing a data source If required you can remoe an existing data source. Procedure 1. Run the following command to list existing data sources: $AdminConfig list DataSource ---> get DS name string 2. Run the following command to remoe the data source: $AdminConfig remoe ds_name_string Where ds_name_string is the name of the data source that you want to remoe. 3. Sae your changes: $sae Results The specified data source is remoed. Related tasks: Creating a data source for a remote database on page 119 Create a CMS datasource on your Dashboard Application Serices Hub instance that a remote database can use. Configuring a hostname to be used by CMS Configure a hostname to be used by CMS. Chapter 7. Configuring Dashboard Application Serices Hub 121

132 About this task You need to set a hostname that CMS can use. For example, in a load balanced enironment, it may not be obious which hostname CMS should use. To specify a hostname to CMS: Procedure 1. On the computer running Dashboard Application Serices Hub, at the command line, change to the following directory: JazzSM_WAS_Profile/bin/CMS 2. Run the cmssetconf command to iew details of the different options that are aailable to you in setting up CMS to use the remote database. Linux./cmssetconf.sh Windows cmssetconf.bat One of the settings that you apply using the cmssetconf command, is the hostname. 3. Run the following command to specify the hostname that you want to use: Linux./cmssetconf.sh -hostname hostname -port console_port_number Windows cmssetconf.bat -hostname hostname -port console_port_number The hostname in now configured. 4. Run the following command to reiew your CMS configuration and erify that you hae correctly specified the hostname: Linux./cmsshowconf.sh -hostname hostname -port console_port_number Windows cmsshowconf.bat -hostname hostname -port console_port_number 5. Stop and restart the serer. What to do next When you hae configured the hostname, you can set up logging for CMS. Configuring logging for CMS Configure a logging for CMS. About this task To configure logging for CMS: Procedure 1. Log in to the Dashboard Application Serices Hub. 2. In the naigation pane, click Console Settings > Websphere Administratie Console and click Launch Websphere administratie console. 3. In the WebSphere Application Serer administratie console naigation pane, click Troubleshooting > Logs and Trace. 4. In the Logging and Tracing page, select the Jazz for Serice Management application serer (serer1). 5. In the General Properties area, select the Change Log Detail Leels link. 6. Under the text panel, expand the All components link. 7. Scroll down and expand the com.ibm.isclite.* entry and then expand the com.ibm.isclite.serice.* entry. 122 Jazz for Serice Management: Configuration Guide Draft

133 8. Under the com.ibm.isclite.serice.* entry, expand the com.ibm.isclite.serice.datastore* entry and click on the com.ibm.isclite.serice.datastore.contextmenu.* entry. 9. From the menu that is displayed, select All Messages and Traces. 10. Scroll through the page and confirm that the text panel includes the following entry: *=info:com.ibm.isclite.serice.datastore.contextmenu.*=all 11. Click OK and in the Logging and Tracing page, in the Message panel, click Sae. Logging is now enabled for CMS. 12. Log out of the Websphere Administratie Console and close it. 13. Log out of the Dashboard Application Serices Hub and close it. 14. Stop and restart the serer. What to do next When you hae configured the logging for CMS, you erify your configuration. Verifying your CMS configuration Verify your CMS configuration. About this task To erify your CMS configuration: Procedure 1. On the computer running Dashboard Application Serices Hub, at the command line, change to the following directory: JazzSM_WAS_Profile/logs/serer1 2. Open the trace.log in a text editor and search for the following string: local updates to database You should find an entry in the log file similar to the following, which indicates that you hae correctly configured CMS with the remote database CMSSynchroniz 1 CMSSynchronizer.localXMLUpdatesAailable() > Initializing, sending local updates to database!!! Chapter 7. Configuring Dashboard Application Serices Hub 123

134 124 Jazz for Serice Management: Configuration Guide Draft

135 Chapter 8. Configuring Registry Serices Creating client certificates Registry Serices functionality can be configured post-installation through a number of mechanisms. Some configuration tasks require accompanying changes to the enironment before they can be completed. You can change Registry Serices configuration primarily through the Registry Serices CLIs and also through changes in the middleware and operating system. Use the Registry Serices CLIs to configure specific Registry Serices settings. For example, you can define a public URL, set the Registry Serices operation mode, customize Resource Shape definitions, and more. For a list of aailable CLIs and details about their operation, see Registry Serices commands. The use of the Registry Serices CLIs might also require the configuration of CLI properties. For the description of each CLI property you can configure, see CLI properties. You can configure Registry Serices to use Client-Cert authentication, so the users that access the application must proide a alid certificate for authentication purposes. About this task You can create: Chained certificates. Self-signed certificates. Certificate authority (CA) certificates. Registry Serices accepts client certificates that are obtained from most of the known certificate authorities. Related information: Certificate management in SSL Creating chained client certificates Create chained client certificates by using the IBM WebSphere Application Serer administratie console. Procedure 1. Open the WebSphere Application Serer administratie console. 2. Select Security > SSL certificate and key management. 3. Select Key stores and certificates > NodeDefaultTrustStore. 4. Select Personal certificates in the Additional Properties cell. 5. Click Create and select Chained certificate from the drop-down list. 6. Enter the required information. Click OK and then Sae. Copyright IBM Corp. 2012,

136 Results The certificate that you created is shown in the Personal certificates panel. What to do next Export the certificate from WebSphere Application Serer truststore to the client keystore. Related tasks: Exporting client certificates After you create a client certificate, use the IBM Key Management tool to export it to a file. This exporting step makes the certificate aailable and ready for the application. Related information: Securing communications Certificate management using ikeyman Creating self-signed client certificates Create self-signed client certificates by using the IBM Key Management tool from IBM WebSphere Application Serer. Procedure 1. Start the ikeyman tool that is in the WAS_HOME\bin directory. 2. Select Key Database File > New. 3. Select PKCS12 from the Key database type drop-down list. 4. In the File Name field, enter the certificate file name. This file extension is.p Select the file location and click OK. 6. When prompted for password, enter and confirm the password to be later used to access the certificate. 7. Click New Self-Signed. 8. Enter the certificate label in the Key Label field, erify the information and click OK. Results The certificate that you created is shown in the Personal certificates panel and saed on the file location you selected. What to do next Import the certificate that you created on the file location that is specified to the client keystore. Creating CA client certificates Create certificate authority (CA) client certificates by using the IBM Key Management tool from IBM WebSphere Application Serer. Procedure 1. Start the ikeyman tool in the WAS_HOME\bin directory. 2. Select Key Database File > New. 126 Jazz for Serice Management: Configuration Guide Draft

137 3. Select PKCS12 from the Key database type drop-down list. 4. In the File Name field, enter the certificate file name. This file extension is.p Select the file location and click OK. 6. When prompted for password, enter and confirm the password to be later used to access the certificate. 7. Click New Self-Signed. 8. Enter the certificate label in the Key Label field, erify the information and click OK. 9. Switch to Signer Certificate list. Select the certificate that you created and click Add. 10. Enter the required information and click OK. 11. Enter a label for the certificate. 12. Click OK. Results The certificate that you created is shown in the Signer certificates panel. What to do next Import the client certificate to the client keystore. Exporting client certificates After you create a client certificate, use the IBM Key Management tool to export it to a file. This exporting step makes the certificate aailable and ready for the application. Before you begin Create a client certificate. Procedure 1. Start the ikeyman tool in the WAS_HOME\bin directory. 2. Select Key Database File > Open. 3. Select PKCS12 from the Key database type drop-down list. 4. In the File Name field, enter the truststore name. This default location to the truststore file is JazzSM_WAS_Profile\\config\cells\cell_name\nodes\ node_name\trust.p Click OK. 6. When prompted for password, enter the default password for WebSphere Application Serer, which is WebAS. 7. From the list of Personal Certificates, select the certificate that you created. 8. Click Export/Import. 9. Select PKCS12 from the Key file type. 10. In the File Name field, enter the certificate file name. This file extension is.p When prompted for password, enter the certificate password. Chapter 8. Configuring Registry Serices 127

138 What to do next Import the client certificate to make it aailable to Registry Serices application. Importing client certificates through web browser You import a certificate that you created to make it aailable to the application. After you create and export your certificate, import it to the Registry Serices application. Before you begin Export the client certificate. About this task This procedure shows how you import client certificates through Mozilla Firefox, but you might use other web browsers aailable. If you use any other browser, see the corresponding documentation for the appropriate steps. Procedure 1. Open the web browser. 2. Select Tools > Options > Encryption. 3. Click View Certificates. 4. In the Certificate Manager panel, Your Certificates tab, click Import Select the exported certificate file and enter the password that you proided when you export the certificate. Results The imported certificate is shown in the Certificate Manager panel and is aailable to the Registry Serices. Importing client certificates through WebSphere Application Serer You import a certificate that you created to make it aailable to the application in the Personal certificates window. Before you begin Create the client certificate. Procedure 1. Open the IBM WebSphere Application Serer administratie console. 2. Select Security > SSL certificate and key management. 3. Select Key stores and certificates > NodeDefaultTrustStore. 4. Select Personal certificates and click Import. 5. Select Key store file and enter the required information: Key store name The full path to the client certificate you created. 128 Jazz for Serice Management: Configuration Guide Draft

139 Type The client certificate type. Choose PKCS12. Key file password The password that you defined when you created the client certificate. 6. Click Get Key File Aliases to enter the Certificate alias to import alue. 7. Click OK then click Sae. Results The imported certificate alias is shown in the Personal certificates panel and is aailable to Registry Serices. Configuring Registry Serices to support HADR mode Registry Serices in Jazz for Serice Management can work with federated DB2 instances. With this support, any Registry Serices instance can keep operating normally if a DB2 node fails. About this task The Registry Serices installation command-line interface (CLI) can configure the JDBC data source that is used by the Registry Serices application in the IBM WebSphere Application Serer. The CLI configures this data source through these CLI properties: ds.jdbc.client.reroutealternateserername ds.jdbc.clientreroutealternateportnumber ds.jdbc.retryinteralforclientreroute ds.jdbc.maxretriesforclientreroute ds.jdbc.clientreroutesererlistjndiname ds.jdbc.blockingreadconnectiontimeout When a connection is rerouted and the JDBC drier is connected to the alternatie DB2 serer, the alternatie serer sends information about its own alternatie serer to the JDBC drier. The JDBC drier then has the information that is required to reroute the connection again if the alternatie DB2 serer is not aailable. The serer that was originally the alternatie serer is now the primary serer, and a new alternatie serer is established. If you enable persistence for client reroute, this new state can be remembered. Without the persistence feature, the JDBC drier must start from the original serer configuration and attempt to connect to the serer that was originally considered the primary serer. If the application serer fails and restarts, the JDBC drier can connect to the DB2 serer that was considered the primary serer at the time of the failure. You can modify these settings after Registry Serices installation is complete through the WebSphere Application Serer administratie console. Chapter 8. Configuring Registry Serices 129

140 Procedure 1. Open the IBM WebSphere Application Serer administratie console. 2. Select Resources > JDBC > Data sources 3. Click datasource_name. By default, this data source name is frs_datasource. 4. On the Additional Properties column, select Custom properties. 5. Modify the data source properties from the list. Related information: High aailability disaster recoery (HADR) and federated databases Configuring client reroute for applications that use DB2 databases Best practices for Registry Serices performance After you install Registry Serices, you can take adantage of its best performance by following specific recommendations. These recommendations and procedures are split into database and application settings, and registration operations. Database settings You can configure specific IBM DB2 settings to get an improed performance out of the Registry Serices database. Separating database tables, logs, and indexes For Registry Serices performance improement, you can separate your database tables, logs, and indexes in dedicate disks. Before you begin Back up the Registry Serices database. Procedure 1. Create a logical olume for each disk that you prepare to use table, logs, and indexes space. 2. Open the IBM DB2 command window by using db2cmd. 3. Open (cd) the DB2_HOME\bin directory. 4. Run db2 restore database database_name from db_backup_location to db_restore_location to restore the database to the directory where you hae the database log files. For example, db2 restore database FRS from /opt/dbbackup/initial to /dbtables/db2. 5. Change the database configuration file by using this command db2 update db cfg for database_name using NEWLOGPATH. 6. Run db2 create bufferpool DISMETA_INDEXBP immediate size 4000 automatic to create the buffer pool for the index table space. 7. Create a table space to include your index by using this command db2 create tablespace DISMETA_INDEX managed by database using (file /dbindexes/db2/db2inst1/dismeta_index.dbf 1G) autoresize yes db2 alter tablespace DISMETA_INDEX bufferpool DISMETA_INDEXBP 8. Modify the db2look file and add the index table space that is named as db2lookfilemodified: db2look -d frs -a -u db2sdin1 -e > db2lookfile. 9. Export the index table space db2moe frs export -sn db2inst1 -l $PWD/lobs. 10. Re-create the database by the db2lookfilemodified: a. Drop all tables by using Linux awk command 130 Jazz for Serice Management: Configuration Guide Draft

141 db2 "select tabname from syscat.tables where tabschema= DB2INST1 " awk {print "Drop table DB2INST1."$1"; " } > drop.txt b. Run the command db2 tf db2lookfilemodified. 11. Run the command db2moe frs LOAD -lo insert -l $PWD/lobs. 12. Set the table integrity by using the command db2 "select tabname from syscat.tables where tabschema= DB2INST1 " awk {print " SET INTEGRITY FOR DB2INST1."$1" IMMEDIATE CHECKED; " } > setint.txt Run this command until no successful string is found in the results file. 13. Restart your application and erify whether Registry Serices enironment is up and running. Finding missing indexes If there is any operation that is running slowly in your enironment and some SQL statement might be causing this performance issue, you can look for missing indexes on DB2. Procedure 1. Capture the DB2 snapshot: a. Turn on the DB2 monitor switches: db2 update monitor switches using bufferpool on LOCK on SORT on STATEMENT on TABLE on UOW on. b. Run the operation whose performance is slow. c. Get the DB snapshot by running the command: db2 get snapshot for all on FRSDB > /location/snapshot.txt. 2. Analyze the DB2 snapshot that you got: a. You can use the IBM Performance Analyst tool to analyze this snapshot. Download the tool from IBM Smarter Performance Analysis Suite. b. Open the tool and select File > Open > DB2::Snapshot. c. Select the file that contains the snapshot and open it. The slow SQL statements show up in red. d. Optional: You can find the most commonly used SQL statements by selecting Profile > most-commonly-used. 3. Get the access plan of the slow SQL statement: a. Connect to the database in use by running: db2 connect to db_name cd install_directory\sqllib\misc; install_directory\sqllib\misc\>#db2 -tf EXPLAIN.DDL; b. Set the explain mode by running: db2 set current explain mode explain DB20000I The SQL command completed successfully. c. Run the slow SQL. d. Get the access plan to a file by running: db2exfmt -d db_name -g db2inst1 -w-1-n%-s%-#0-oaccess_plan_file 4. Add an index that is based on the access plan by running this command: db2 CREATE INDEX db2inst1.index_name ON db2inst1.table_name (col_name ASC, col_name ASC, col_name ASC) ALLOW REVERSE SCANS. 5. Verify the performance results after you added this index by running steps 1 to 3 again. Chapter 8. Configuring Registry Serices 131

142 What to do next If the index you added does not help getting improed performance results, check whether you added an appropriate index. Setting database transaction log files For Registry Serices performance improement, increase the size of your transaction log file. Before you begin The alue that you set for your transaction log file size might ary according to your enironment. For large-scale enironments, set the LOGFILSIZ parameter to at least If you do not adjust this alue to your enironments needs, Registry Serices might become unresponsie while it processes concurrent requests. Procedure 1. For Windows systems, open the DB2 command window by using db2cmd. For Linux systems, log in as the DB2 user instance, which is db2inst1 by default. 2. Run db2 update database config for database_name using LOGFILSIZ log_file_size LOGPRIMARY primary_log LOGSECOND secondary_log to increase the size of your database transaction log files. For example, db2 update database config for FRSDB using LOGFILSIZ LOGPRIMARY 40 LOGSECOND Restart your database with the following commands db2 deactiate database database_name and db2 actiate databse database_name. 4. Optional: You can erify the size of your log files by running the following command db2 get db config for database_name grep -i logfilsiz. Results After you complete these settings, the db2 command displays the following result: Log gile size (4KB) (LOGFILSIZ) = Application serer settings You can configure specific IBM WebSphere Application Serer settings to get an improed performance out of the Registry Serices application. After you install the Registry Serices application, you can use the WebSphere Application Serer administratie console to configure settings to aoid performance issues. Maximum number of threads The alue that you must set as the maximum number of threads depends on the workload of the system where the Registry Serices application is installed. The maximum number of threads must be equal to or greater than the maximum number of requests concurrently running on your system. For example, if your system is running 200 concurrent requests, set the thread pool maximum number alue to at least Jazz for Serice Management: Configuration Guide Draft

143 Connection pool size The number of connection pools that might request connections from the application, like the IBM DB2 database, helps you to determine the connection pool size. Start with the number you can estimate from your usual daily workload and monitor the application connection status. If the number of concurrent waiting processes is greater than zero, but the processor load is not close to 100%, increase the connection pool size. If the processor load is low, under normal workload, decrease the connection pool size. Setting the connection pool size to a alue greater than the maximum number of threads is not useful. Heap size requirement Determining the heap size alue for your system depends on your system workload. Garbage collection adapts the heap size to a alue between 40% and 70% out of the maximum occupancy. Heap size alues oer 70% causes frequent garbage collection cycles, which reduce performance. Values under 40% reduce the number of cycles, which causes those cycles to last longer and means longer paused interals. When you set the heap size through those steps, check the Verbose garbage collection option to force WebSphere Application Serer to print each garbage collection cycle in the JazzSM_WAS_Profile\logs\serer_name\natie_stderr.log. This file shows the alue of heap size that is used during high workload on your system. You can also use the perfanalyst tool to iew the garbage collection log. Download this tool from IBM Smarter Performance Analysis Suite. Based on the result, you can adjust your maximum JVM heap size. Registration operations With Registry Serices installed on your system enironment, you can run registration operations. Follow the guidelines for running concurrent operations to aoid performance issues. Registration in batch If you hae a large amount of Resource Records to be registered, use the registration in batch procedure. Howeer, to aoid haing a batch registration that affects your system performance, follow these recommendations: Include around 10 records per batch registration. A high number of records on a single batch registration operation might represent a performance issue. Maintain all relationships in one batch. For example, if you hae ResourceA depending on ResourceB, keep them together in the same batch registration operation. Aoid running massie registration operation in concurrence with other operations. Plan to run this operation when your system workload is low. Chapter 8. Configuring Registry Serices 133

144 Deletion operations With Registry Serices installed on your system enironment, after you run registration operation, you can also delete records. Follow the guidelines for running deletion operations to aoid performance issues. Serice Proider records deletion When you use the Registry Serices CLI command to delete Serice Proider records, configure these settings: 1. On IBM DB2, set the transaction log space by using the command: db2 update db cfg for FRSDB using logprimary 60 logsecond 40 logfilsiz On Linux system, set the ulimit alue by using the command: ulimit -n Open the /etc/sysctl.conf file and edit the line: fs.file-max = Sae the file and restart the system. 4. On IBM WebSphere Application Serer, open the WebSphere Application Serer administratie console. 5. Select Application serers > serer_name > Process definition > Jaa Virtual Machine. 6. Set Maximum heap size to 2048 MB. 7. Select Data sources > datasource_name > Connection pools. 8. Set Maximum connections to 30 and Mininum connections to Jazz for Serice Management: Configuration Guide Draft

145 Chapter 9. Configuring Security Serices When you run IBM Installation Manager, the installation program automatically configures the Authentication Serice. Authentication Serice configuration The installation program deploys the IBMESSAuthnSc.ear file, which is the Authentication Serice application, to the IBM WebSphere Application Serer. It assigns the TrustClientRole security role to all authenticated users. The installation program also copies the Authentication Serice files to the SECURITY_HOME directory. Authentication and single sign-on configuration All integration serices in the Jazz for Serice Management require that you configure WebSphere Application Serer to use a central federated repository with an LDAP user registry. Single sign-on capabilities in the Jazz for Serice Management require that each integration serice and its application serer use LTPA as the authentication mechanism. After you hae configured LTPA, you can generate LTPA keys and synchronize them across multiple application serers in the Jazz for Serice Management distributed enironment. Update the Authentication Serice configuration You can update an Authentication Serice configuration by using AdminTask object commands, including: Running the isessconfigured command to erify that the Authentication Serice is configured. Running the modifyessltpaconfiguration command to modify the LTPA configuration of the Authentication Serice. Response signing key management You can manually create, import, or export Authentication Serice response signing key by using AdminTask object commands. Related concepts: Security Serices references These references describe the set of AdminTask object commands and Python scripts that are run with the wsadmin scripting tool to configure the Authentication Serice. Copyright IBM Corp. 2012,

146 136 Jazz for Serice Management: Configuration Guide Draft

147 Chapter 10. Configuring Tioli Common Reporting Getting started with reports Tioli Common Reporting requires authenticated access to all its features. You can configure Tioli Common Reporting to use basic authentication and single sign-on. You must set up your reporting enironment before users can work with reports, for example, import packages, create data source connections, or create report packages. Before you begin 1. Install Tioli Common Reporting. 2. If required, install Framework Manager to create your own data models.. 3. Configure the Framework Manager connection to Tioli Common Reporting. See Configuring Framework Manager connection on page 140. About this task After you install Tioli Common Reporting, prepare your report packages to generate, publish, and edit your reports. Procedure 1. If you hae the report packages ready, complete the following tasks: Import Cognos report packages into your workspace.. If you hae BIRT packages, import them into your workspace. a. Create or update your data sources: For Cognos report packages, configure the database connection. See Configuring database connections on page 141. For BIRT report packages, ensure that the report package data sources point to the existing data sources. Use the trcmd-list command to see your data source settings, and the trcmd-modify command to modify them, if necessary. Tip: BIRT reports are separate from Cognos. To create or modify BIRT reports, use open source BIRT report designer. The designer is not shipped with Tioli Common Reporting. It is aailable to download from the Eclipse site. 2. To create a report package: a. Configure a database connection to a data source. See Configuring database connections on page 141. b. Create a data model in Framework Manager. Tip: For more instructions, see the Framework Manager User Guide in Cognos information center. c. Import the metadata from your data sources. When you import the metadata, you can start modeling in Framework Manager. You can define the relations between objects such as tables, iews, and queries; you can select the layers to define which objects you want to make isible; you can Copyright IBM Corp. 2012,

148 define what you want to publish; and you can create and publish a package that contains the model and reports. For more information, see the Framework Manager User Guide. When you configure the connection between Framework Manager and Tioli Common Reporting, the published package is automatically pushed to Tioli Common Reporting and you can see it in its respectie folder in the reporting interface. d. Log in to the releant reporting interface in your enironment. Logging in to the reporting interface. e. Select Launch > Query Studio to test your model and create simple ad hoc reports, or select Launch > Report Studio to create more complex reports. f. Import Cognos report packages into your workspace.. Logging in to the reporting interface Fix Pack 1 Depending upon your organization s deployment of Tioli Common Reporting, you can access the reporting interface directly or through Dashboard Application Serices Hub, or through a Tioli product s user interface. About this task With the Common Reporting interface, you can perform simple lightweight tasks as well as more adanced scalable reporting that is proided by IBM Cognos Business Intelligence Reporting. Create on-demand reports. Use the Web-based report authoring. reports. Tip: To access the Cognos documentation, click in the reporting interface. You can access the reporting interface as follows: Dashboard Application Serices Hub Log in to the reporting interface from the Dashboard Application Serices Hub login page. Both Dashboard Application Serices Hub and Tioli Common Reporting are installed in the same application sering enironment, and the reporting interface is integrated with Dashboard Application Serices Hub. Access is determined by user roles associated with user IDs. The role that you need to access Tioli Common Reporting is tcrportaloperator. Direct access Log in to the reporting interface from its own login page. Tioli product s user interface Log in to the reporting interface from a Tioli product s login page. Tioli Common Reporting is integrated with a Tioli product. Procedure Access the reporting interface from Dashboard Application Serices Hub as follows: 1. Open a web browser and enter the following URL for the Jazz for Serice Management UI and reporting serer: 138 Jazz for Serice Management: Configuration Guide Draft

149 For example: host.domain is the fully qualified host name or IP address of the Jazz for Serice Management UI and reporting serer. Note: When single sign-on (SSO) is enabled, ensure that you use the fully qualified host name in the URL of the Jazz for Serice Management reporting and UI serer. SSO requires that the browser pass LTPA cookies to the Jazz for Serice Management application serer, and these cookies contain the fully qualified host name. port is the secure HTTP port number that was specified during installation. The default alue is /DASH_context_root is the context root for the console that was specified during installation. The default alue is /ibm/console. Check with your organization s Jazz for Serice Management administrator if you are unsure of the URL. 2. On the Dashboard Application Serices Hub login page, enter the user ID and password. Ensure that user ID has access to Tioli Common Reporting. Click Log in. The Dashboard Application Serices Hub Welcome page opens. Tip: To eliminate the security warnings when logging on to the user interface, install a certificate on the Jazz for Serice Management UI and reporting serer. To install the certificate, follow the instructions in WebSphere information center. 3. In the naigation bar, click > Common Reporting. The Common Reporting portal is displayed within a Dashboard Application Serices Hub portlet page. Access the reporting interface directly as follows: 1. Open a web browser and enter the following URL for the reporting interface: For example: host.domain is the fully qualified host name or IP address of the Jazz for Serice Management reporting serer. Note: When single sign-on (SSO) is enabled, ensure that you use the fully qualified host name in the URL of the Jazz for Serice Management reporting serer. SSO requires that the browser pass LTPA cookies to the Jazz for Serice Management application serer, and these cookies contain the fully qualified host name. port is the non secure HTTP port number that was specified during installation. The default alue is Check with your organization s Jazz for Serice Management administrator if you are unsure of the URL. 2. On the Log on to IBM Cognos Software page, enter the user name and password. Click OK. The Common Reporting portal opens. Access the reporting interface from a Tioli product s user interface. Chapter 10. Configuring Tioli Common Reporting 139

150 Check with your organization s Tioli product administrator for the URL of the Tioli product s login page. Configuring Framework Manager connection Framework Manager is a separately installable application used to model reports. If you installed it in a location different from the default one, you need to configure it to run with the Cognos-based Tioli Common Reporting engine and user interface. This step is especially important if you installed Framework Manager on a separate computer. Before you begin Make sure that you extracted and installed the Framework Manager component aailable from the installation media on the computer where you want to model reports. Before you install Framework Manager, ensure that the JAVA_HOME enironment ariable is not set. Framework Manager is deliered together with its own ersion of Jaa, so if you hae JAVA_HOME set to Jaa ersion already installed on your computer, Framework Manager configuration might fail to start. If you installed Framework Manager on a system other than the system where Tioli Common Reporting engine is installed, the data source must exist on this Framework Manager system and on the Tioli Common Reporting engine system. Procedure 1. Open the Framework Manager configuration program by running Framework_Manager_install_dir\bin\cogconfigw.exe Tip: The default Framework Manager installation directory is c:\%program Files%\cognos\bin\cogconfigw.exe 2. Select Explorer > Enironment. The Properties panel opens. 3. In the Gateway Settings section, modify alue in the Gateway URI field. Change the alue for the Cognos Gateway URI from tarf/serlet/dispatch, which is the default alue, to JazzSMSerer_Hostname:16310/tarf/serlet/dispatch. JazzSMSerer_Hostname refers to the fully qualified host name of the Jazz for Serice Management application serer on which Tioli Common Reporting is installed. 4. In the Other URI Settings section, modify alue for the Dispatcher URI for external applications field. Change the alue for the Dispatcher URI from which is the default alue, to JazzSMSerer_Hostname refers to the fully qualified host name of the Jazz for Serice Management application serer on which Tioli Common Reporting is installed. Note: The URIs in Step 3 and Step 4 must match the URIs configured for Tioli Common Reporting in IBM Cognos Configuration. Open IBM Cognos Configuration by running c10_location/bin64/tcr_cogconfig.sh script (non-windows systems) or c10_location\bin64\tcr_cogconfig.bat (Windows systems) on the Jazz for Serice Management application serer. 5. Sae the new configuration. 140 Jazz for Serice Management: Configuration Guide Draft

151 What to do next You can now start modeling your reports with the use of Framework Manager. You will need to log in twice because Framework Manager does not support single sign-on. Content Store setting in Cognos Configuration Fix Pack 1 This feature enables you to update the Content Store connection in Cognos Configuration when a new Content Store database needs to be used. About this task Use this task to change the Content Store settings in Cognos Configuration. This task can also be used to point Cognos to an existing Content Store database. Note: Ensure to take a backup of the database before you make this change, as Cognos Configuration makes changes to the Content Store schema, which cannot be rolled back. Procedure 1. Start the Cognos Configuration by following one of these methods: From the Start menu, start the IBM Cognos Configuration. Open the Cognos Configuration by running: AIX Linux System z c10_location/bin64/tcr_cogconfig.sh Windows c10_location\bin64\tcr_cogconfig.bat 2. In the Explorer iew, expand Data Access > Content Manager. 3. Click IBM DB2 Content Store. IntheIBM DB2 Content Store - Database - Resource Properties page, update the Content Store fields accordingly 4. Click Sae. 5. Exit Cognos Configuration. Configuring database connections Tioli Common Reporting proides a new mode of connection called Dynamic Query Mode (DQM) along with the Compatible mode (using natie database client). About this task DQM is a 64-bit reporting engine, so it better utilizes aailable hardware, resulting in performance improement with large olumes of data. DQM also offers key query optimizations to address query complexity and data olumes with improed query execution. It also proides adanced query capabilities, such as in-memory caching, that proide benefits for query planning, execution, and results while maintaining users' security permissions. Note: DQM was introduced in Tioli Common Reporting Version 3.1. Because DQM is Jaa-based, another added benefit is the ease of data source setup using JDBC. This means that you do not need to install platform-specific database Chapter 10. Configuring Tioli Common Reporting 141

152 driers or catalog nodes and databases. DQM does not replace the 'compatible' reporting engine that is in Tioli Common Reporting Version 2.x, but it does offer many benefits oer the compatible reporting engine. For more benefits of DQM, see the DQM guide at: %2Fcom.ibm.swg.ba.cognos.dyn_query doc%2Fc_dqm_dyn_query_mode.html &path%3d5_3_2 The reporting archie package defines which connection type the package requires. If the package was created with DQM then a JDBC connection is required. Otherwise natie driers are required, as for Tioli Common Reporting Version To identify which data source type is required by a report package, first import the package into Tioli Common Reporting, then in the Action column, click the Properties icon next to the imported package. If the Query Mode is Dynamic, then the package requires a JDBC connection to be configured. If the Query Mode is Compatible, then the package requires a natie database client connection. Related information: IBM Cognos Administration and Security Guide - Data Sources and Connections Cognos Business Intelligence Software Enironments - Relational Databases Cognos Business Intelligence Software Enironments - Dynamic Query Mode Cognos Business Intelligence Software Enironments - ODBC Creating a JDBC database connection for dynamic query mode Create a JDBC database connection for report packages that use Dynamic Query Mode. Before you begin Perform this task with the support of a database administrator. About this task You can only create JDBC database connections for report packages that use dynamic query mode. Dynamic Query Mode (DQM) is recommended for new applications of IBM Cognos Business Intelligence Reporting. For more information on dynamic query mode, see: infocenter/cbi/10r2m0/index.jsp?topic= %2Fcom.ibm.swg.ba.cognos.dyn_query doc%2Fc_dqm_dyn_query_mode.html &path%3d5_3_2 Procedure 1. Copy your database's JDBC drier JAR files to the following locations: JazzSM_WAS_Profile/installedApps/localhostNode01Cell/IBM Cognos.ear/p2pd.war/WEB-INF/lib/ JazzSM_HOME/reporting/cognos/webapps/p2pd/WEB-INF/lib/ 142 Jazz for Serice Management: Configuration Guide Draft

153 Note: For a DB2 database, no copy is required because the JAR files already exist in the Tioli Common Reporting enironment. For other database types, check its documentation for list of required JDBC drier JAR files. 2. Create a database connection for Cognos as follows: a. Log in to the releant reporting interface in your enironment. Logging in to the reporting interface on page 138. b. Select Launch > Administration. c. In the Configuration tab, click to add a data source. d. Use the New Data Source wizard to create the data source with regard to the following points: On the second page of the wizard, select DB2 or Oracle database as the Type, that is, do not select JDBC. Ensure that the Configure JDBC connection option is selected. On the third page of the wizard, enter only the database name, and in the Signon section, specify the User ID and password for connection to the database. On the fourth page, enter the Serer name, Port number, and the Database name. Results Note: The connection may fail the connection test for compatibility. This can be ignored, as the Compatible connection type is not being used. You hae now connected your Tioli Common Reporting to a database using a JDBC connection that can be used for dynamic query mode reports. Connecting to a DB2 database in Compatible mode Connect Tioli Common Reporting to a DB2 database. Before you begin Perform this task with the support of a database administrator. Make sure that you installed the DB2 database client on the computer where Cognos-based Tioli Common Reporting engine is installed. You can use either the 32-bit or 64-bit client, howeer, if you decide to use the 64-bit DB2 client, you must use the 32-bit ersions of the library files from the directory sqlib/lib32. The ersion of the client must match the ersion of your database. About this task To configure the database, connect it to a client, and actiate the optional cross-database functionality. Procedure 1. Edit WebSphere Application Serer scripts to use the settcren script. To do this, append JazzSM_Home/reporting/bin/setTCRen.sh to the JazzSM_WAS_Profile/bin/setupCmdLine.sh. Chapter 10. Configuring Tioli Common Reporting 143

154 2. Windows Linux Connect the DB2 database client to the database serer by running the Configuration Assistant and configuring the local net serice name configuration. For details, see Configuring client-to-serer connections in the DB2 information center. Important: Note the name of the connection you hae created as it is used in one of the following steps. Additionally, for non-windows platforms, the Tioli Common Reporting must be able to find the local DB2 libraries. To ensure this, check if the DB2 directory containing libraries exists. Then, configure the system library path to point to the database client library directory by modifying the following enironment ariable: AIX LIBPATH HP-UX SHLIB_PATH Linux Solaris LD_LIBRARY_PATH For example, you can modify the settcren.sh script by inserting the following line: export LD_LIBRARY_PATH=/opt/IBM/db2/V10.1/lib32:$LD_LIBRARY_PATH For non-windows systems, you might also need to source the DB2 profile in the Tioli Common Reporting enironment before starting the serer, for example. /home/db2 user/sqllib/db2profile. You can modify the settcren.sh script by inserting the following line before starting WebSphere Application Serer:. /home/db2 user/sqllib/db2profile, where db2 user is your local DB2 user ID. 3. Restart WebSphere Application Serer: a. Stop the serer by running the JazzSM_WAS_Profile\bin\stopSerer serer_name command. b. Start the serer by running the JazzSM_WAS_Profile\bin\startSerer serer_name command. JazzSM_WAS_Profile is the location of Jazz for Serice Management WebSphere Application Serer profile and by default is: /opt/ibm/jazzsm/profiles for UNIX systems and C:\Program Files\IBM\JazzSM\profile for Windows systems. By default, serer_name is serer1. 4. Create new database connection for Cognos by following the steps: a. From the Common Reporting portlet, go to Launch expandable list, and choose the Administration. b. On the Configuration tab, add a data source by clicking. c. Follow the New Data Source wizard as required noting the following steps: On the second panel, choose a DB2 database as Type and clear the Configure JDBC connection option. On the third panel, specify the name of the connection you noted before as the DB2 database name, and in the Signon section specify User ID and Password for connecting with the database. Results You hae now connected your Tioli Common Reporting to a DB2 database instance. 144 Jazz for Serice Management: Configuration Guide Draft

155 Connecting to an MS SQL database in Compatible mode Connect the Tioli Common Reporting to an MS SQL database. Before you begin Perform this task with the support of a database administrator. Make sure that you installed an MS SQL database client on the computer where Cognos-based Tioli Common Reporting engine is installed. About this task To configure the database, connect the database to a client, and actiate the optional cross-database functionality. Procedure 1. Connect the MS SQL client to the database serer by running the MS SQL Management Studio Express, configuring the local net serice name configuration, and restarting your system. Important: Note the name of the connection you hae created as it is used in one of the following steps. 2. Create a database connection for Cognos as follows: a. Log in to the releant reporting interface in your enironment. Logging in to the reporting interface on page 138. b. Select Launch > Administration. c. In the Configuration tab, click to add a data source. d. Follow the New Data Source wizard as required noting the following steps: On the second panel, choose an MSSQL Serer database as Type and clear the Configure JDBC connection option. On the third panel, specify the name of the connection that you noted before as the Serer name, and in the Signon section specify a new User ID and Password. Results You hae now connected your Tioli Common Reporting to an MS SQL database. Connecting to an Oracle database in Compatible mode Connect the Tioli Common Reporting to an Oracle database. Before you begin Perform this task with the support of a database administrator. Make sure that you installed the 32-bit Oracle database client on the computer where Cognos-based Tioli Common Reporting engine is installed. Important: You might need to export the TNS_ADMIN enironment ariable before starting the Tioli Common Reporting serer. The TNS_ADMIN ariable in the settcren.sh script must be set to point to the directory where the Oracle tnsnames.ora file is. See the Oracle documentation for details. Chapter 10. Configuring Tioli Common Reporting 145

156 About this task To configure the database, connect it to a client, configure calculations for Oracle functions, and actiate the optional cross-database functionality. Procedure 1. Edit WebSphere Application Serer scripts to use the settcren script. To do this, append REPORTING_HOME/bin/setTCRen.sh to the JazzSM_WAS_Profile/bin/setupCmdLine.sh. 2. Ensure that Tioli Common Reporting can find Oracle 32-bit databases: a. Check if the Oracle directory containing 32-bit libraries exists. b. Start the WebSphere administratie console; for example, select Start > IBM WebSphere > IBM WebSphere Application Serer > Profiles > JazzSMProfile > Administratie console. c. Enter the WebSphere administrator user ID and password, and click Log in. d. Select Serers > Serer Types > WebSphere Application Serer. e. Select the serer used by Jazz for Serice Management. The default is serer1. f. In the Serer Infrastructure section, select Jaa and Process Management and then Process Definition. g. In the Additional Properties section, select Enironment Entries. h. If necessary, create or modify the ariable to include the path to Oracle client library directory: AIX LIBPATH HP-UX SHLIB_PATH Linux Solaris LD_LIBRARY_PATH For example: LD_LIBRARY_PATH=/opt/IBM/JazzSM/reporting/cognos/bin64:/ opt/oracle/app/oracle/product/11.2.0/client/lib i. Sae your changes. 3. Connect the Oracle database client to the database serer by running the Oracle Net Configuration Assistant, configuring the local net serice name configuration, and restarting your system. Important: Note the name of the connection you hae created as it is used in one of the following steps. 4. Restart the Jazz for Serice Management application serer. See Restarting Jazz for Serice Management application serers on page Create a database connection for Cognos as follows: a. Log in to the releant reporting interface in your enironment. Logging in to the reporting interface on page 138. b. Select Launch > Administration. c. In the Configuration tab, click to add a data source. d. Follow the New Data Source wizard as required noting the following steps: On the second panel, choose an Oracle database as Type and unselect Configure JDBC connection. On the third panel, specify the name of the connection that you noted before as the SQL*Net connect string, and in the Signon section specify a new User ID and Password. 146 Jazz for Serice Management: Configuration Guide Draft

157 Results You hae now connected your Tioli Common Reporting to an Oracle database. Configuring distributed installation for load balancing You can configure your reporting system to obtain higher performance and usability leels while running reports by adding another reporting engine system, and ensure failoer. Before you begin An existing instance of Tioli Common Reporting has been installed. Attention: To enable load balancing, both instances of Tioli Common Reporting must be at the same ersion leel. About this task Load balancing allows you to hae multiple user interfaces and reporting engines installed, which distribute and balance loads among the computers. This, in turn, improes scalability in an enironment where there is a large olume of report requests to process. It also ensures failoer. The following diagram presents how arious components are linked together to ensure load balancing. Procedure 1. Install a second instance of Tioli Common Reporting reusing the existing Content Store. Attention: When you attempt to reuse a Content Store, a warning is displayed in relation to ersion of the Content Store database. You must acknowledge the warning to proceed. 2. For each instance of Tioli Common Reporting locate and edit the following file in a text editor: REPORTING_HOME/lib/configuration/urlconfiguration.properties a. For each urlconfiguration.properties add an entry to include the fully qualified domain name for the serer on which Tioli Common Reporting is installed, as follows: urlproider.hostname=fully qualified domain name Note: A fully qualified domain name (FQDN) includes both the hostname and the domain name, for example, serer1.tioli.ibm.com. b. Optional: If you do not plan to install SSL certificates for the IBM WebSphere Application Serer instances associated with the Tioli Common Reporting instances, you can disable warnings associated with SSL certificates by disabling HTTPS by making further edit to urlconfiguration.properties. To do so, add the following entry: urlproider.protocol=http and replace the secure port (default is 16311) with the non-secure port (default is 16311) in the following entry: urlproider.portnumber= Use a common user repository (for example, Lightweight Directory Access Protocol (LDAP)) for both Tioli Common Reporting instances. See Configuring Jazz for Serice Management for a central user registry. Chapter 10. Configuring Tioli Common Reporting 147

158 4. Install and configure an HTTP serer to balance incoming requests across both instances of Tioli Common Reporting. For more information, see: Preparing the HTTP serer for load balancing on page 92 Results User requests coming into the HTTP serer are load balanced to the Tioli Common Reporting instances. As the Tioli Common Reporting instances connect to the same Content store, the reporting engines are also load-balanced and share the same reporting artifacts. What to do next 1. To finish the configuration, see the following topics of the IBM Cognos information center: Balance requests among reporting engines. You can set the way in which the requests are handled among the dispatchers. Use cluster compatible mode for dispatchers. You can change the way in which the load is balanced in your infrastructure. 2. Learn how to: Start and stop dispatchers and serices. Actiate a Content Manager serice Remoe dispatchers from your enironment. Related concepts: Load balancing for Dashboard Application Serices Hub on page 81 You can set up a load balanced cluster of console nodes with identical configurations to eenly distribute user sessions. Configuring security permissions Increase the security settings for the Common Reporting user permissions. By default, all the users created, including the one specified during the installation process, hae full administratie priileges in IBM Cognos. You can modify the security permissions in Cognos Administration. About this task To learn more about Tioli Common Reportingsecurity settings for authorizations, see Authentication and authorization in Tioli Common Reporting on page 149, and Cognos Administration and Security Guide. In Dashboard Application Serices Hub, only those users that are assigned to the Dashboard Application Serices Hub tcrportaloperator role can access the Common Reporting interface within the Dashboard Application Serices Hub portlet page, referred to as the Common Reporting portlet. When users are assigned to this role, they also hae full Cognos administratie priileges in the reporting interface. All new users of the Common Reporting portlet are assigned to the Cognos Eeryone user group. This user group is a member of the CognosSystem Administrators role by default. To improe security, edit the members of the System Administrators role. You can change the settings for this role in Cognos Administration. 148 Jazz for Serice Management: Configuration Guide Draft

159 Procedure 1. Log in to the releant reporting interface in your enironment. See Logging in to the reporting interface on page In the reporting interface, select Launch > Administration. 3. In the Security tab, select Users, Groups, and Roles in the naigation bar, and click the Cognos namespace. 4. Use the naigation icons to browse the list and locate System Administrators. Click More > Set propertiesto set the role properties. Tip: You might need to go to the last page to locate the System Administrators role. 5. In the Members tab, click Add to add an indiidual administratie user. 6. Add the administratie user of your choice from the VMMProider namespace, and click OK to sae the settings. Tip: Select to Show users in the list to be able to see the users. Beginning with Tioli Common Reporting 2.1.1, the default is not to return all groups and users that require the administrator to use the search function. 7. Remoe the Eeryone user group from the System Administrators role by selecting the check box, and clicking Remoe. 8. Click OK to sae the new settings. Authentication and authorization in Tioli Common Reporting Security in Tioli Common Reporting is based on Cognos security. It is also based on Dashboard Application Serices Hub security when Tioli Common Reporting is integrated with Dashboard Application Serices Hub. Learn about how they work together and how to authorize specific users or groups to reporting items. Authentication During installation, Tioli Common Reporting is configured to use the Federated Repository, which is required for authentication to work successfully in Tioli Common Reporting. You must use the Federated Repository to authenticate users. The authentication mechanism can be the build-in default repository, LDAP, Actie Directory, or other repository supported by the WebSphere Federated Repository. When installing Tioli Common Reporting, the Federated Repository is configured to use Internal File Repository. This repository contains users and groups and is built into Tioli Common Reporting. It does not require the users or groups to exist anywhere outside Tioli Common Reporting. Users and groups in the File Repository are managed by WebSphere on which Tioli Common Reporting was installed. After the installation, you can add an LDAP or Actie Directory into Tioli Common Reporting Federated Repository as an additional source. Authorization In the reporting interface, authorization to the reporting artifacts is controlled through Cognos reporting-related roles to which users or groups can be mapped. You can manage Cognos roles in the reporting interface by accessing Cognos Administration > Security tab > Users, Groups, and Roles. Chapter 10. Configuring Tioli Common Reporting 149

160 By default, all users in the reporting interface are assigned to the Cognos Eeryone user group. This user group is a member of the CognosSystem Administrators role by default. You must remoe eeryone from the System Administrators role to limit authorization access. See Configuring security permissions on page 148. In Dashboard Application Serices Hub, authorization to access the Common Reporting portlet is controlled through the Dashboard Application Serices Hub tcrportaloperator role. You can manage this role in Dashboard Application Serices Hub by accessing Console Settings > User Roles or Console Settings > Group Roles. Important: The Dashboard Application Serices Hub tcrportaloperator role does not control access to the reporting artifacts in the reporting interface. Constraining access to reports Manage permissions granted to users or user groups for reports and capabilities for reports, report sets, or folders. By default, permissions and capabilities that user groups or reports are assigned are inherited from the parent entry. About this task You can change the default permissions that specific groups or users hae to reports or report packages. You can also change capabilities for reports, report sets, and folders. Procedure 1. Log in to the releant reporting interface in your enironment. Logging in to the reporting interface on page Naigate to the report for which you want to change user permissions and select it. 3. Click the Set properties icon ( ). 4. Go to the Permissions tab. The table shows default permissions set for user groups. 5. Select Oerride the access permissions acquired from the parent entry and choose the types of permissions that you want to grant to specific user groups. Tip: Use the search function to display users, as Tioli Common Reporting by default does not return all groups and users. 6. Go to the Capabilities tab. In the table you can see what capabilities are assigned to reports, report sets or folders. 7. Select Oerride the capabilities acquired from the parent entry to grant and deny capabilities. What to do next To find out more about permissions and capabilities, see IBM Cognos Administration and Security Guide. Configuring sample audit reports Actiate sample audit reports to iew information about user and report actiity. 150 Jazz for Serice Management: Configuration Guide Draft

161 Before you begin To use audit reports, you must direct logging to a database and increase the log leel. For information about configuring the logging database, see Configuring a Repository for Log Messages. Tip: In this procedure, the logging database tables are created at serer startup. If you hae a policy that only database administrators can create the tables, you can use the c10_location\configuration\schemas\logging\database_type\ LS_dblnit_database_type.sql script to create them. The directories for JDBC driers are: JazzSM_WAS_Profile\installedApps\ localhostnode01cell\ibm Cognos.ear\p2pd.war\WEB-INF\lib and c10_location\webapps\p2pd\web-inf\lib. Additionally, for DB2 on z systems: c10_location\bin64. About this task Audit reports are created based on the data from the logging database. This information can help you plan your capacity, monitor performance, or identify unused content. For more information about audit reports and log settings, see Cognos Administration and Security Guide. You can find the sample audit report package in c10_location\webcontent\samples\ content. Procedure Set up audit reporting. Set up sample audit reports Set up the Sample Report Usage audit report: 1. Add the following XML fragment to the web.xml.nocm and web.xml.withcm files located at JazzSM_WAS_Profile\installedApps\localhostNode01Cell\ IBM Cognos.ear\p2pd.war\WEB-INF\lib. <serlet> <serlet-name>dsserlet</serlet-name> <serlet-class>com.cognos.demo.dsserlet</serlet-class> </serlet> <serlet-mapping> <serlet-name>dsserlet</serlet-name> <url-pattern>/cognos/dsserlet.jsp</url-pattern> </serlet-mapping> The url-pattern alue can be anything you choose. 2. Create the JazzSM_WAS_Profile\installedApps\localhostNode01Cell\IBM Cognos.ear\p2pd.war\WEB-INF\classes\com\cognos\demo directory if you do not already hae it. 3. Copy the build.bat (Windows) or build.sh (UNIX) file from c10_location\webapps\audit to JazzSM_WAS_Profile\installedApps\ localhostnode01cell\ibm Cognos.ear\p2pd.war\WEB-INF\classes\com\ cognos\demo. 4. Update the build script with Tioli Common Reporting JAVA_HOME and Cognos location: set JAVA_HOME=JazzSM_WAS_Profile\jaa set CRN_HOME=c10_location. Chapter 10. Configuring Tioli Common Reporting 151

162 5. Copy the DSSerlet.jaa file from c10_location\webapps\audit directory to JazzSM_WAS_Profile\installedApps\localhostNode01Cell\IBM Cognos.ear\p2pd.war\WEB-INF\classes\com\cognos\demo. 6. In the DSSerlet.jaa file, uncomment the bind call and fill in a Tioli Common Reporting user, password, and namespace. The default namespace is VMMProider. Update the endpoint (URL) to cognos/dsserlet.jsp. 7. In the command-line interface, run build.bat (Windows) or build.sh (UNIX) from JazzSM_WAS_Profile\installedApps\localhostNode01Cell\IBM Cognos.ear\p2pd.war\WEB-INF\classes\com\cognos\demo. Ensure a class file is generated. 8. Restart Tioli Common Reporting. 9. If you are using an application serer other than Tomcat, rebuild the application file and then redeploy IBM Cognos BI to the application serer. For instructions, see.cognos Installation and Configuration Guide. 10. Create a data source connection to the XML data source: a. In the reporting console, click Launch > Administration. b. On the Configuration tab, click New Data Source. c. Under Name, type url_xml and click Next. d. Under Type, select XML and click Next. e. In the Connection string field, enter cognos/dsserlet.jsp. 152 Jazz for Serice Management: Configuration Guide Draft

163 Appendix. Jazz for Serice Management references Common directory locations The references contain information and examples for command-line interfaces, scripts, and properties files that are proided by the integration serices. It also contains a reference for different directories and paths that the integration serices use. Jazz for Serice Management topics use path name ariables for paths to common directories, for example, home directories. Jazz for Serice Management home directory The JazzSM_HOME ariable describes the location where Jazz for Serice Management is installed. This location can be specified during installation. If not specified, the following default locations are used: Root user installations: AIX Linux System z /opt/ibm/jazzsm Windows C:\Program Files\IBM\JazzSM Non-root user installations: AIX Linux System z /home/nonrootuser_name/ibm/jazzsm Windows C:\Users\nonrootuser_name\IBM\JazzSM Jazz for Serice Management profile directory The JazzSM_WAS_Profile ariable describes the location of the application serer profile that is used for Jazz for Serice Management. This location is in the /profile/ subdirectory of the Jazz for Serice Management home directory. Root user installations: AIX Linux System z /opt/ibm/jazzsm/profile Windows C:\Program Files\IBM\JazzSM\profile Non-root user installations: AIX Linux System z /home/nonrootuser_name/ibm/jazzsm\profile Windows C:\Users\nonrootuser_name\IBM\JazzSM\profile Jazz for Serice Management profile name The JazzSM_Profile_Name ariable refers to the name assigned to the WebSphere Application Serer profile for Jazz for Serice Management. The default name is JazzSMProfile. Installation images home directory The Install_Imgs_Home ariable describes the common root directory that contains the extracted contents of the installation images depending on the installation scenario. Copyright IBM Corp. 2012,

164 Full installation IBM DB2, IBM WebSphere Application Serer, and IBM Tioli Common Reporting if you want to install Tioli Common Reporting during the full installation flow. Attention: You must extract the contents of the installation media for this software to the same common root directory, otherwise the full installation displays error messages for missing software. Custom installation IBM WebSphere Application Serer, if you do not want to use an existing installation; Tioli Common Reporting if you want to install it after a custom installation of the other integration serices. Note: It is not necessary to extract the contents of the installation media for this software to the same common root directory, but it is preferable to maintain all extracted installation media in a central location. Jazz for Serice Management installation images home directory The JazzSM_Image_Home ariable describes the common root directory in which the Jazz for Serice Management is extracted. It contains the launchpad, IBM Installation Manager, IBM Prerequisite Scanner, the Installation Manager repository with the software packages for the integration serices except Tioli Common Reporting, and IBM Tioli Directory Integrator. Tip: Ensure that the path to the JazzSM_Image_Home directory does not contain any spaces or special characters, otherwise the launchpad does not start. IBM DB2 home directory The DB2_HOME ariable describes the location where IBM DB2 is installed. This location was specified during installation. If not specified, the following default locations are used: On UNIX systems: /opt/ibm/db2 for root user installations and $HOME/sqllib for non-root user installations, where $HOME represents the non-root user's home directory. On Windows systems: C:\Program Files\IBM\SQLLIB WebSphere Application Serer home directory The WAS_HOME ariable describes the location where WebSphere Application Serer is installed. This location was specified during installation. If not specified, the following default locations are used: Root user installations: AIX Linux System z /opt/ibm/websphere/appserer Windows C:\Program Files\IBM\WebSphere/AppSerer Non-root user installations: AIX Linux System z /home/nonrootuser_name/ibm/websphere/ AppSerer Windows C:\Users\nonrootuser_name\IBM\WebSphere/AppSerer 154 Jazz for Serice Management: Configuration Guide Draft

165 Administration Serices home directory The ADMIN_HOME ariable describes the location where Administration Serices is installed. This location can be specified during installation. If not specified, the following default locations are used: Root user installations: AIX Linux System z /opt/ibm/jazzsm/admin Windows C:\Program Files\IBM\JazzSM\admin Non-root user installations: AIX Linux System z /home/nonrootuser_name/ibm/jazzsm\admin Windows C:\Users\nonrootuser_name\IBM\JazzSM\admin Administration Serices UI home directory The ADMINUI_HOME ariable describes the location where Administration Serices UI is installed. This location can be specified during installation. If not specified, the following default locations are used: Root user installations: AIX Linux System z /opt/ibm/jazzsm/adminui Windows C:\Program Files\IBM\JazzSM\adminui Non-root user installations: AIX Linux System z /home/nonrootuser_name/ibm/jazzsm\adminui Windows C:\Users\nonrootuser_name\IBM\JazzSM\adminui Registry Serices home directory The REGISTRY_HOME ariable describes the location where Registry Serices is installed. This location can be specified during installation. If not specified, the following default locations are used: Root user installations: AIX Linux System z /opt/ibm/jazzsm/registry Windows C:\Program Files\IBM\JazzSM\registry Non-root user installations: AIX Linux System z /home/nonrootuser_name/ibm/jazzsm\registry Windows C:\Users\nonrootuser_name\IBM\JazzSM\registry Security Serices home directory The SECURITY_HOME ariable describes the location where Security Serices is installed. This location can be specified during installation. If not specified, the following default locations are used: Root user installations: AIX Linux System z /opt/ibm/jazzsm/security Windows C:\Program Files\IBM\JazzSM\security Non-root user installations: AIX Linux System z /home/nonrootuser_name/ibm/jazzsm\security Appendix. Jazz for Serice Management references 155

166 Windows C:\Users\nonrootuser_name\IBM\JazzSM\security Dashboard Application Serices Hub home directory The DASH_HOME ariable describes the location where Dashboard Application Serices Hub is installed. This location can be specified during installation. If not specified, the following default locations are used: Root user installations: AIX Linux System z /opt/ibm/jazzsm/ui Windows C:\Program Files\IBM\JazzSM\ui Non-root user installations: AIX Linux System z /home/nonrootuser_name/ibm/jazzsm\ui Windows C:\Users\nonrootuser_name\IBM\JazzSM\ui Dashboard Application Serices Hub profile directory The DASH_Profile ariable describes the location of the application serer profile that is used for Dashboard Application Serices Hub. This location is in the /profiles/ subdirectory of the Jazz for Serice Management home directory. Root user installations: AIX Linux System z /opt/ibm/jazzsm/profile Windows C:\Program Files\IBM\JazzSM\profile Non-root user installations: AIX Linux System z /home/nonrootuser_name/ibm/jazzsm/profile Windows C:\Users\nonrootuser_name\IBM\JazzSM\profile Tioli Common Reporting home directory The REPORTING_HOME directory that contains the uninstallation program, the installation log files, and Tioli Common Reporting component files. If not specified, the following default locations are used: Root user installations: AIX Linux System z /opt/ibm/jazzsm/reporting Windows C:\Program Files\IBM\JazzSM\reporting Non-root user installations: AIX Linux System z /home/nonrootuser_name/ibm/jazzsm\ reporting Windows Not supported IBM Cognos installation directory The c10_location directory that contains the Cognos installation. If not specified, the following default locations are used: Root user installations: AIX Linux System z /opt/ibm/jazzsm/reporting/cognos Windows C:\Program Files\IBM\JazzSM\reporting\cognos Non-root user installations: 156 Jazz for Serice Management: Configuration Guide Draft

167 AIX Linux System z /home/nonrootuser_name/ibm/jazzsm\ reporting\cognos Windows Not supported Full installation log directory The Full_install_log_dir directory into which general and offering specific logs are created during full installation: On UNIX systems: $HOME/jazzsm_launchpad/logs/ On Windows systems: %userprofile%\jazzsm_launchpad\logs\ IBM Prerequisite Scanner installation directory The ips_root directory that contains the contents of the extracted Prerequisite Scanner platform package. If not specified, the default locations are used: On UNIX systems: Install_Imgs_Home/PrereqScanner/UNIX_Linux On Windows systems: Install_Imgs_Home\PrereqScanner\Windows Restarting Jazz for Serice Management application serers Some configuration or administration tasks for an integration serice require that you restart the IBM WebSphere Application Serer. Stopping a Jazz for Serice Management application serer impacts all integration serices installed in the associated WebSphere Application Serer profile. Remember: Only stop Jazz for Serice Management application serers during your enterprise s scheduled maintenance window. Stopping Jazz for Serice Management application serers You can stop any Jazz for Serice Management application serer by using the IBM WebSphere stopserer command. You might need to restart the application serer after completing a configuration task for an integration serice, or stop the application serer for maintenance. About this task Your chosen topology and impacted integration serices determine the Jazz for Serice Management application serer to stop. Table 25 on page 158 summarizes which Jazz for Serice Management application serer to stop depending on your topology and installed integrated serices. Appendix. Jazz for Serice Management references 157

168 Table 25. Determining the Jazz for Serice Management application serer to start. This table summarizes how to determine the Jazz for Serice Management application serer to stop in each topology based on the integration serices installed on the application serer in the topology. Topology Single serer Two serer topology Three serer topology Three serer topology Four serer topology Four serer topology Installed integrated serices Any, some, or all of the following integration serices: Administration Serices Administration Serices UI Dashboard Application Serices Hub Registry Serices Security Serices Tioli Common Reporting Any, some, or all of the following integration serices: Administration Serices Administration Serices UI Dashboard Application Serices Hub Registry Serices Security Serices Tioli Common Reporting Any, some, or all of the following integration serices: Administration Serices Registry Serices Security Serices Any, some, or all of the following integration serices: Administration Serices Administration Serices UI Dashboard Application Serices Hub Tioli Common Reporting Any, some, or all of the following integration serices: Administration Serices Registry Serices Security Serices Any, some, or all of the following integration serices: Administration Serices Administration Serices UI Dashboard Application Serices Hub Jazz for Serice Management application serer Composite application and database serer Composite serer Enterprise serer UI and reporting serer Enterprise serer UI serer 158 Jazz for Serice Management: Configuration Guide Draft

169 Table 25. Determining the Jazz for Serice Management application serer to start (continued). This table summarizes how to determine the Jazz for Serice Management application serer to stop in each topology based on the integration serices installed on the application serer in the topology. Topology Four serer topology Installed integrated serices Any, some, or all of the following integration serices: Administration Serices Tioli Common Reporting Jazz for Serice Management application serer Reporting serer The same procedure applies to any Jazz for Serice Management application serer. Procedure 1. On the releant Jazz for Serice Management serer, open a command window. 2. Change to the JazzSM_WAS_Profile/bin directory. 3. Run the following command: AIX Linux System z./stopserer.sh serer_name -username WAS_admin_user_name -password WAS_admin_password Windows stopserer.bat serer_name -username WAS_admin_user_name -password WAS_admin_password serer_name Enter the name of the application serer that was specified when the application serer profile was created, for example, serer1. WAS_admin_user Specify the WebSphere administrator to connect to the application serer. WAS_admin_password Specify the password for the WebSphere administrator. Example stopserer serer1 -username jazzsmwasadmin -password jazzsmpwd Related information: stopserer command Starting Jazz for Serice Management application serers You can start any Jazz for Serice Management application serer by using the IBM WebSphere startserer command. You might need to restart the application serer after completing a configuration task for an integration serice, or after taking the application serer down for maintenance. About this task Your chosen topology and impacted integration serices determine the Jazz for Serice Management application serer to start. Appendix. Jazz for Serice Management references 159

170 Table 26 summarizes which Jazz for Serice Management application serer to start depending on your topology and installed integrated serices. Table 26. Determining the Jazz for Serice Management application serer to start. This table summarizes how to determine the Jazz for Serice Management application serer to start in each topology based on the integration serices installed on the application serer in the topology. Topology Single serer Two serer topology Three serer topology Three serer topology Four serer topology Four serer topology Installed integrated serices Any, some, or all of the following integration serices: Administration Serices Administration Serices UI Dashboard Application Serices Hub Registry Serices Security Serices Tioli Common Reporting Any, some, or all of the following integration serices: Administration Serices Administration Serices UI Dashboard Application Serices Hub Registry Serices Security Serices Tioli Common Reporting Any, some, or all of the following integration serices: Administration Serices Registry Serices Security Serices Any, some, or all of the following integration serices: Administration Serices Administration Serices UI Dashboard Application Serices Hub Tioli Common Reporting Any, some, or all of the following integration serices: Administration Serices Registry Serices Security Serices Any, some, or all of the following integration serices: Administration Serices Administration Serices UI Dashboard Application Serices Hub Jazz for Serice Management application serer Composite application and database serer Composite serer Enterprise serer UI and reporting serer Enterprise serer UI serer 160 Jazz for Serice Management: Configuration Guide Draft

171 Table 26. Determining the Jazz for Serice Management application serer to start (continued). This table summarizes how to determine the Jazz for Serice Management application serer to start in each topology based on the integration serices installed on the application serer in the topology. Topology Four serer topology Installed integrated serices Any, some, or all of the following integration serices: Administration Serices Tioli Common Reporting Jazz for Serice Management application serer Reporting serer The same procedure applies to any Jazz for Serice Management application serer. Procedure 1. On the releant Jazz for Serice Management serer, open a command window. 2. Change to the JazzSM_WAS_Profile/bin directory. 3. Run the following command: AIX Linux System z./startserer.sh serer_name Windows startserer.bat serer_name serer_name Enter the name of the application serer that was specified when the application serer profile was created, for example, serer1. Related information: startserer command Jazz for Serice Management CLI references Integration serices proide command-line interfaces to support configuration, administration, and other tasks. Jazz for Serice Management deployment commands With deployment commands, you can manage a Jazz for Serice Management application serer's configuration. smsetapplicationserer command Fix Pack 2 Use the smsetapplicationserer command to manage the configuration properties of a Jazz for Serice Management application serer. Syntax smsetapplicationserer.bat --property autostart=true false --property "admin.user=admin_user_name" -- property "admin.password=admin_user_password" [--help] Appendix. Jazz for Serice Management references 161

172 Parameters --property autostart=true false Specify the property to manage the Jazz for Serice Management application serer as a serice. When the property is set to true, the command can complete some or all of the following actions: Creates the serice if it does not exist Starts the serice if it is not started When the property is set to false, the command can complete some or all of the following actions: Checks the status of the serice Stops the serice if it is not stopped Deletes the serice if it exists --property "admin.name=admin_user_name" Specify the user name with administratie priileges who can change the configuration settings of the Jazz for Serice Management application serer. --property "admin.password=admin_user_password" Specify the password that is associated with the administrator user name as set by the admin.user property. Example Windows smsetapplicationserer.bat --property autostart=true --property "admin.user=admin_user1" --property "admin.password=mypassword" Dashboard Application Serices Hub command reference Use the Dashboard Application Serices Hub command line interface consolecli commands for writing scripts for passing information between applications. Restriction: When running consolecli.sh bat commands in Tioli Integrated Portal enironments, you must use tipcli.sh/bat instead. That is, the consolecli.sh bat commands replaced the tipcli.sh/bat commands with the release of Dashboard Application Serices Hub. The consolecli commands are entered in the DASH_HOME/bin directory. The consolecli component proides help for its arious commands: Help [--command command_name] Access help for all commands or optionally you can use the command argument to return detailed help for a specific command. The following returns help for the AddUpdatePreferenceProfile command: consolecli.bat Help --command AddUpdatePreferenceProfile Help ---- AddUpdatePreferenceProfile --username <console_username> --password <passwordforuser> --profilename <profilename> [--newprofilename <newprofilename>] [--themedir <th emedir>] [--shownatree <true false>] [--componentdir <default ltr rtl>] [--text Dir <default contextual ltr rtl>] [--iews <iewlist>] [--roles <rolelist>] [--d efaultview <defaultview>] where <console_username> is the username in the console that has iscadmins role. 162 Jazz for Serice Management: Configuration Guide Draft

173 <passwordforuser> is the password for the user. <profilename> is profile name which will be created or updated. <newprofilename> is the new name for the existing preference profile. <themedir> is the directory name of the installed theme. Example: DASHLight <shownatree> specify if show naigation tree by default after login the conso le. <componentdir> specify component direction for the console. <textdir> specify text direction for the console. <iewlist> is iews assignment for the preference profile. <rolelist> is roles assignment for the preference profile. <defaultview> specify which iew is displayed by default after login the conso le. CTGWA4017I The command completed successfully. Working with roles Use these tipcli commands for to manipulate roles. ListRoles List all roles. AddRole --username tip_username --password tip_user_password --rolename role_name Add the specified role. Console users are granted access to resources based on the role to which they hae been assigned. All roles that are created hae a resource type of Custom. Note: Arguments to the role_name parameter should not include spaces. UpdateRole --username tip_username --password tip_user_password --rolename role_name --newrolename new_role_name Change the name of a specified role to the supplied new role name. Note: Arguments to the role_name and newrolename parameters should not include spaces. DelRole --username tip_username --password tip_user_password --rolename role_name Delete the specified role. Note: Arguments to the role_name parameter should not include spaces. ListRolesFromGroup --username tip_username --password tip_user_password --groupid group_id List all roles associated with a specified user group. MapRolesToGroup --username tip_username --password tip_user_password --groupid group_id --roleslist role_name1, role name2 Associate a comma separated list of roles with a particular user group. RemoeRolesFromGroup --username tip_username --password tip_user_password --groupid group_id --roleslist role_name1, role name2 Disassociate a comma separated list of roles from a particular user group. ListRolesForPage --pageuniquename page_unique_name List all roles associated with a specified page. MapRolesToPage --username tip_username --password tip_user_password --pageuniquename page_unique_name --roleslist role_name1, role name2 --accessleellist leel1, leel2 Associate a comma separated list of roles with a particular page and set the access leel to the page for each role. Appendix. Jazz for Serice Management references 163

174 RemoeRolesFromPage --username tip_username --password tip_user_password --pageuniquename page_unique_name --roleslist role_name1, role name2 Disassociate a comma separated list of roles from a particular page. ListRolesForPortletEntity --portletentityuniquename portlet_entity_unique_name List all roles associated with a specified portlet. MapRolesToPortletEntity --username tip_username --password tip_user_password --portletentityuniquename portlet_entity_unique_name --roleslist role_name1, role name2 --accessleellist leel1, leel2 Associate a comma separated list of roles with a particular portlet and set the access leel to the portlet for each role. RemoeRolesFromPortletEntity --username tip_username --password tip_user_password --portletentityuniquename portlet_entity_unique_name --roleslist role_name1, role name2 Disassociate a comma separated list of roles from a particular portlet. ListRolesFromUser --username tip_username --password tip_user_password --userid user_id List all roles associated with a specified user ID. MapRolesToUser --username tip_username --password tip_user_password --userid user_id --roleslist role_name1, role name2 Associate a comma separated list of roles with a particular user ID. RemoeRolesFromUser --username tip_username --password tip_user_password --userid user_id --roleslist role_name1, role name2 Disassociate a comma separated list of roles from a particular user ID. ListRolesForView --iewuniquename iew_name List all roles associated with a specified iew. MapRolesToView --username tip_username --password tip_user_password --iewuniquename iew_name --roleslist role_name1, role name2 --accessleellist leel1, leel2 Associate a comma separated list of roles with a particular iew and set the access leel for the iew for each role. RemoeRolesFromView --username tip_username --password tip_user_password --iewuniquename iew_name --roleslist role_name1, role name2 Disassociate a comma separated list of roles from a particular iew. Working with iews consolecli commands for working with iews. The consolecli commands are entered in the DASH_HOME/bin. ListViews List all iews. AddViewMembers --username console_username --password console_user_password --iew iew_unique_name [--members members1, member2] [--launchmembers launch_member1, launch_member2] Add members or launch members for a specified iew. Important: When you add members to a iew at the command line, your updates are not reflected in the console until the next time that you log in. ListViewsForRole --rolename role_name List the iews associated with a specified role. 164 Jazz for Serice Management: Configuration Guide Draft

175 MapViewsToRole --username console_username --password console_user_password --rolename role_name --iewlist iew_unique_name1, iew_unique_name2 --accessleellist leel1, leel2 Associate a comma separated list of iews with a particular role and set the access leel for the role for each iew. RemoeViewsFromRole --username console_username --password console_user_password --rolename role_name --iewlist iew_unique_name1, iew_unique_name2 Disassociate a comma separated list of iews from a particular role. Working with users consolecli commands for working with users. ListUsersFromRole --rolename role_name List the users associated with a specified role. MapUsersToRole --username console_username --password console_user_password --rolename role_name --userslist user_id1:user_id2 Associate a colon (:) separated list of user IDs with a particular role. Note: Arguments to the userslist parameter should not include a colon (:). RemoeUsersFromRole --username console_username --password console_user_password --rolename role_name --userslist user_id1:user_id2 Disassociate a colon (:) separated list of user IDs from a particular role. Working with preference profiles consolecli commands for working with preference profiles. DeletePreferenceProfile --username console_username --password console_user_password --profilename profile_name Delete the specified preference profile. ListPreferenceProfiles [--name profile_name] Return a list of console preference profiles. Optionally, you can specify a comma separated lists of preference profiles, to return their unique names. ShowPreferenceProfile --uniquename profile_unique_name List all the attributes for a specified profile preference. AddUpdatePreferenceProfile --username console_username --password console_user_password --profilename profile_name [--newprofilename new_profile_name] [--themedir theme_dir] [--shownatree true false] [--componentdir default ltr rtl] [--textdir default contextual ltr rtl] [--iews iew_unique_name1, iew_unique_name2] --roles role_name1, role_name2] [--defaultview iew_unique_name] Use the AddUpdatePreferenceProfile command to create a new profile preference or update an existing profile. Table 27. AddUpdatePreferenceProfile command arguments Parameter and arguments Description --username console_username Mandatory parameter. A user with the iscadmins role. --password console_user_password Mandatory parameter. The password for the user with the iscadmins role. --profilename profile_name Mandatory parameter. The name of the profile that is to be created or modified. Appendix. Jazz for Serice Management references 165

176 Table 27. AddUpdatePreferenceProfile command arguments (continued) Parameter and arguments Description [--newprofilename new_profile_name] Optional parameter. The new name for the specified profile. [--themedir theme_dir] Optional parameter. Used to specify the directory for the theme that you want to apply. [--shownatree true false] Optional parameter. Used to specify whether or not you want the naigation pane to be displayed for preference profile. [--componentdir default ltr rtl] Optional parameter. Used to specify component display direction, that is, whether you want items to display left-to-right, right-to-left, or to use the default browser settings. [--textdir default ltr rtl] Optional parameter. Used to specify text direction, that is, whether you want text to display left-to-right, right-to-left, or to use the default browser settings. [--iews iew_unique_name1, iew_unique_name2] --roles role_name1, role_name2] [--defaultview iew_unique_name] Optional parameter. Used to specify the iews that you want to assign to the preference profile. Comma separated list. Optional parameter. Used to specify the roles that you want to assign to the preference profile. Comma separated list. Optional parameter. Used to specify the iew that you want displayed when a user logs into the console. Working with widgets consolecli commands for working with widgets. The consolecli commands are entered in the DASH_HOME/bin. ListWidgetEntitiesForRole --rolename role_name] List the widgets entities associated with a specified role. MapWidgetEntitiesToRole --username console_username --password console_user_password --rolename role_name --widgetentitylist widgetentity_unique_name1, widgetentity_unique_name2 --accessleellist leel1, leel2 Associate a comma separated list of widgets with a particular role and set the access leel for the role for each widget. RemoeWidgetEntitiesFromRole --username console_username --password console_user_password --rolename role_name --widgetentitylist widgetentity_unique_name1, widgetentity_unique_name2 Disassociate a comma separated list of widgets with from particular role. Working with dashboards consolecli commands for working with dashboards. ListDashboards [--iewlist iew_unique_name1, iew_unique_name2] [--customizedashboards true false] List all dashboards. You can optionally filter the list by using the iewlist 166 Jazz for Serice Management: Configuration Guide Draft

177 parameter and proiding a comma separated list of iews. You can also use the customizedashboards (set totrue) to return a list of custom dashboards only. ListDashboardsForRole --rolename role_name List the dashboards associated with a specified role. MapDashboardsToRole --username console_username --password console_user_password --rolename role_name --dashboardlist dashboard_unique_name1, dashboard_unique_name2 --accessleellist leel1, leel2 Associate a comma separated list of dashboards with a particular role and set the access leel for the role for each dashboard. RemoeDashboardsFromRole --username console_username --password console_user_password --rolename role_name --dashboardlist dashboard_unique_name1, dashboard_unique_name2 Disassociate a comma separated list of dashboards from a particular role. Working with user groups consolecli commands for working with user groups. The consolecli commands are entered in the DASH_HOME/bin directory. ListGroupsFromRole --rolename role_name List the user groups associated with a specified role. MapGroupsToRole --username console_username --password console_user_password --rolename role_name --groupslist group_name1: group_name2 Associate a colon (:) separated list of groups with a particular role. Note: Arguments to the groupslist parameter should not include a colon (:). RemoeGroupsFromRole --username console_username --password console_user_password --rolename role_name --groupslist group_name1: group_name2 Disassociate a colon (:) separated list of groups from a particular role. Charting consolecli commands consolecli commands for working with charting. ListCharts --username console_username --password console_user_password Use ListCharts to reiew the charts that are configured in the enironment. ChartConnection --action action [--name name] [--protocol protocol --hostname hostname --port port -- sericename sericename --username username --password password--renderformat render_format --Datasource_Username datasource_username --credentialtype credential_type] --username console_username --password console_user_password ChartConnection is used to configure a connection to any IBM Tioli Charting Web Serice. The ITM Web Serice is just one example. ChartExport --dir output_directory --type all customcharts dashboard [--dashboardid dashboard_id --dashboardname dashboard_name] --username console_username --password console_user_password ChartExport is used to export chart data. Appendix. Jazz for Serice Management references 167

178 Table 28. ChartExport command arguments Parameter and arguments --dir output_directory --type all customcharts dashboard [--dashboardid dashboard_id --dashboardname dashboard_name] --username console_username --password console_user_password Description Mandatory parameter. The directory where the exported data is saed. If the directory does not exist, it is created. Mandatory parameter. If you set the --type to all, then all charts are exported. If you set it to customcharts, then only customized charts are exported. If you set it to dashboard, then you can use either the --dashboardid or the --dashboardname parameter to specify the dashboard for which you want to export chart data. Optional parameter. If you set the --type parameter to dashboard, then you can use either the --dashboardid or the --dashboardname parameter to specify the dashboard for which you want to export chart data. Mandatory parameter. The user name for a user with either the chartadministrator or chartcreator role. Mandatory parameter. The password for the specified user name. ChartImport --dir source_directory --username console_username --password console_user_password ChartImport is used to import chart data from a specified directory. Table 29. ChartImport command arguments Parameter and arguments --dir source_directory --username console_username --password console_user_password Description Mandatory parameter. The directory where the data to be imported is located. BIRT Designer file format is.rptdesign. Mandatory parameter. The user name for a user with either the chartadministrator or chartcreator role. Mandatory parameter. The password for the specified user name. ChartProperties [--name property_name --alue property_alue] --username console_username --password console_user_password ChartProperties is used to iew or modify properties for charting. If you only proide username and password details and no other arguments, then the current properties are listed. It is useful to run this command first so that you can reiew the current property names and alues before you decide to make updates. 168 Jazz for Serice Management: Configuration Guide Draft

179 Table 30. ChartProperties command arguments Parameter and arguments Description --name property_name --alue property_alue --username console_username --password console_user_password Optional parameter. The name of the property that you want to update and the alue that you want to set. For example, to set the timeout alue to 10,000,000 milliseconds, enter --name AXIS_TIMEOUT --alue Mandatory parameter. The user name for a user with the chartadministrator role. Mandatory parameter. The password for the specified user name. ListRestoreTimestamp Use the ListRestoreTimestamp command to return a list of charting store backups by timestamp. RestoreChartStore --BackupTimestamp backup_timestamp --username console_username --password console_user_password Use the RestoreChartStore command to restore a chart store by timestamp. Table 31. RestoreChartStore command arguments Parameter and arguments Description RestoreChartStore --BackupTimestamp Mandatory parameter. The timestamp of the charting store backup. --username console_username Mandatory parameter. The user name for a user with the chartadministrator role. --password console_user_password Mandatory parameter. The password for the specified user name. ContentBox CLI commands Use these ContentBox CLI commands to assist you in setting up your custom ContentBox implementation. namespacecontentbox command: Use the namespacecontentbox command to rename ContentBoxTemplate.war and ensure that it can be uniquely identified in the Dashboard Application Serices Hub enironment. Syntax This command has the following syntax: UNIX Linux namespacecontentbox.sh -template path_to_contentboxtemplate.war -outputdir path_to_output_dir -newname new_name -newversion new_ersion Windows namespacecontentbox.bat -template path_to_contentboxtemplate.war -outputdir path_to_output_directory -newname new_name -newversion new_ersion Appendix. Jazz for Serice Management references 169

180 Example Linux UNIX For example, in a UNIX or Linux enironment, use the following command: DASH_HOME/bin/namespaceContentBox.sh -template DASH_HOME/bin/ ContentBoxTemplate.war -outputdir DASH_HOME/output -newname My_Company_My_Product -newversion 1.0 Where: DASH_HOME is location of the Dashboard Application Serices Hub instance that is to be associated with the WAR file. DASH_HOME/bin/ContentBoxTemplate.war is the location of ContentBoxTemplate.war. DASH_HOME/profiles/TIPProfile/installableApps is where you want the namespaced WAR to be located. My_Company_My_Product is a unique name for the renamed WAR file. 1.0 is the ersion string that you want to associate with the WAR. deploycontentbox command: Use the deploycontentbox command to deploy a custom WAR that was created using ContentBoxTemplate.war and has been renamed using the namespacecontentbox command. Syntax This command has the following syntax: UNIX Linux deploycontentbox.sh -username WAS_admin_user_ID -password WAS_admin_user_password -war path_to_war_location -dashhome DASH_home_dir -contextroot context_root_path -oerwrite true false Windows deploycontentbox.bat -username WAS_admin_user_ID -password WAS_admin_user_password -war path_to_war_location -dashhome DASH_home_dir -contextroot context_root_path -oerwrite true false Note: The WebSphere Application Serer must be in stopped mode before you run the command. Example Linux UNIX For example, in a UNIX or Linux enironment, use the following command: /tmp/contentbox/bin/deploycontentbox.sh -username wsadmin_username -password wsadmin_password -war /tmp/contentbox/mycompany_myproduct.war -dashhome /opt/jazzsm/ui -contextroot /MyCompany_MyProduct -oerwrite true Where: wsadmin_username is the WebSphere Application Serer administrator user ID. wsadmin_password is the WebSphere Application Serer administrator user password. /tmp/contentbox/mycompany_myproduct.war is the file path to the customized WAR that is to be deployed. 170 Jazz for Serice Management: Configuration Guide Draft

181 /opt/jazzsm/ui is the path to the Dashboard Application Serices Hub home directory. /MyCompany_MyProduct is the context root for the customized WAR. The context root alue must be based on the name of the WAR. For example, if you named the WAR as NameSpacedContentBox.war, then the context root alue is /NameSpacedContentBox. true indicates that you want to oerwrite settings for an existing WAR. Use the false option to ensure that existing settings are not oerwritten. undeploycontentbox command: Use the undeploycontentbox command to undeploy a WAR file that was deployed using the deploycontentbox command. Syntax This command has the following syntax: UNIX Linux undeploycontentbox.sh -username WAS_admin_user_ID -password WAS_admin_user_password -dashhome DASH_home_dir -name name_of_custom_war Windows undeploycontentbox.bat -username WAS_admin_user_ID -password WAS_admin_user_password -dashhome DASH_home_dir -name name_of_custom_war Note: The WebSphere Application Serer must be in stopped mode before you run the command. Example Linux UNIX For example, in a UNIX or Linux enironment, use the following command: /tmp/contentbox/bin/undeploycontentbox.sh -username wsadmin -password wsadmin_pa55w0rd -dashhome /opt/jazzsm/ui -name MyCompany_MyProduct.war Where: wsadmin is the WebSphere Application Serer administrator user ID. wsadmin_pa55w0rd is the WebSphere Application Serer administrator user password. /opt/jazzsm/ui is the path to the Dashboard Application Serices Hub home directory. MyCompany_MyProduct.war is the name of the namespaced custom WAR that was deployed using the deploycontentbox command. tipcli - Export plugins Use the Export command to export customization data for an instance of the Jazz for Serice Management application serer. Use the ListExportPlugins command to list plugins that are aailable for export. Restriction: When running consolecli.sh bat commands in Tioli Integrated Portal enironments, you must use tipcli.sh/bat instead. That is, the consolecli.sh bat commands replaced the tipcli.sh/bat commands with the release of Dashboard Application Serices Hub. Appendix. Jazz for Serice Management references 171

182 Attention: These instructions assume that you are exporting data from a Tioli Integrated Portal enironment and not a Dashboard Application Serices Hub one. Therefore, the file paths and commands are documented in relation to a Tioli Integrated Portal instance. For example, commands are documented using tipcli instead of consolecli. For Dashboard Application Serices Hub enironments, substitute the tipcli element of the command with consolecli. Syntax ListExportPlugins Use the ListExportPlugins command to list all plugins that can be exported. Use the list of returned plugins to assist you when you are specifying plugins to be exported. Export [--includeplugins --excludeplugins plugin1,plugin2] [--settingfile setting_file] --username tip_username --password tip_user_password Parameters If you proide no parameters to the Export command, all custom data is exported by default. Note: If you specify additional parameters for the tipcli.bat.sh Export and make a typing error, that is, if you type a parameter incorrectly, or use the incorrect case, then the commands runs as if no parameters were specified and no warning message is displayed. Export parameters and arguments: [--includeplugins --excludeplugins plugin1,plugin2] Optional parameter. You can choose to include or exclude a list of plugins when you run the Export command. [--settingfile setting_file] Optional parameter. You can specify your export requirements in properties file instead of specifying your requirements using separate parameters at the command line. Proide a path to the settings file as the argument to the settingfile parameter. On systems running Windows you must use double backslashes characters (\\) when specifying the path to your settings file, for example, C:\\tmp\\export.properties. Command line parameters take precedence oer entries in the settings file. --username tip_username Mandatory parameter. The user name for a user with the iscadmin role. --password tip_user_password Mandatory parameter. The password for the specified user name. Example 1 - Return a list of plugins aailable for exporting The following example returns a list of plugins that can be exported: C:\IBM\tioli\tip22\profiles\TIPProfile\bin>tipcli.bat ListExportPlugins Example 2 - Export a subset of aailable plugins Windows The following example exports the CMS plugin only: Windows 172 Jazz for Serice Management: Configuration Guide Draft

183 C:\IBM\tioli\tip22\profiles\TIPProfile\bin>tipcli.bat Export --includeplugins com.ibm.tioli.tip.cli.cms.cmsexportplugin --username admin_user --password admin_user_password tipcli - Adanced Export options: Use the ExportPagePlugin tipcli command to export specific Jazz for Serice Management application serer data. Restriction: When running consolecli.sh bat commands in Tioli Integrated Portal enironments, you must use tipcli.sh/bat instead. That is, the consolecli.sh bat commands replaced the tipcli.sh/bat commands with the release of Dashboard Application Serices Hub. Attention: These instructions assume that you are exporting data from a Tioli Integrated Portal enironment and not a Dashboard Application Serices Hub one. Therefore, the file paths and commands are documented in relation to a Tioli Integrated Portal instance. For example, commands are documented using tipcli instead of consolecli. For Dashboard Application Serices Hub enironments, substitute the tipcli element of the command with consolecli. Note: If you specify additional parameters for the tipcli.bat.sh Export and make a typing error, that is, if you type a parameter incorrectly, or use the incorrect case, then the commands runs as if no parameters were specified and no warning message is displayed. Export [--exportfile export_file] [--pages ALL NONE page1,page2] [--iews ALL NONE iew1,iew2] [--roles ALL NONE REQUIRED role1,role2] [--exportpagesinviews true false] [--userpreferences ALL NONE REQUIRED user_id1,user_id2] [--consolepreferenceprofiles ALL NONE pref_id1,pref_id2] [--includeentitiesfromapp war1,war2] [--includecustomdata true false] [--includecredentialdata true false] [--includemytasks true false] [--includemystartuppages true false] [--includetransformations true false] --username tip_username --password tip_user_password Table 32. ExportPagePlugin command arguments Parameter and arguments Description [--exportfile export_file] Optional parameter. Specifies the path and file name for the exported data, for example, c:/tmp/extest.zip. [--pages ALL NONE page1,page2] Optional parameter. If you do not use the pages parameter, the default setting is ALL unless either exportpagesinviews or includeentitiesfromapp is defined, then the default setting is NONE. You can also proide a list of pages that you want to export. Appendix. Jazz for Serice Management references 173

184 Table 32. ExportPagePlugin command arguments (continued) Parameter and arguments Description [--iews ALL NONE iew1,iew2] --exportpageiniews [true false] [--roles ALL NONE REQUIRED role1,role2] [--exportpagesinviews true false] [--userpreferences ALL NONE REQUIRED user_id1,user_id2] [--consolepreferenceprofiles ALL NONE pref_id1,pref_id2] [--includeentitiesfromapp war1,war2] [--includecustomdata true false] [--includecredentialdata true false] [--includemytasks true false] Optional parameter. If you do not use the iews parameter, the default setting is ALL. You can also proide a list of iews that you want to export and optionally specify that you want to export all pages associated with the specified iews. Note: Whether the optional parameter exportpageiniews is set to true or false, if a iew has a default node in the naigation pane associated with it, then the page associated with the node is always exported. This is also true, een if you specify NONE as the argument to the --pages parameter. Optional parameter. You can export no roles, all roles, or a specific list of roles. The default setting is ALL unless the pages parameter or the includeentitiesfromapp parameter is specified. Then, the default setting is set to REQUIRED. Optional parameter. Use this parameter, set to true, to export the pages associated with an exported iew. The default alue is false. Optional parameter. You can export preferences for all users, no users, or for a specified list of users by user ID. The default setting is ALL. This parameter oerrides the includemytasks and includemystartuppages parameters. Optional parameter. You can export no preference profile data, all preference profile data, or data for a specific list of preference profiles. The default setting is ALL. Note: If a console preference profile has a custom iew as its default iew, then that iew is automatically exported. If the exported iew has a default node in the naigation pane, then the associated page is automatically exported with the iew. Optional parameter. You can proide a list of WARs to export pages that contain widgets associated with the listed WARs. Optional parameter. The default alue is true. If is set to false, no customization data is exported. Optional parameter. The default alue is true. If is set to false, no credential data is exported. Optional parameter. The default setting is true. This parameter only applies when the includeentitiesfromapp parameter is also specified. 174 Jazz for Serice Management: Configuration Guide Draft

185 Table 32. ExportPagePlugin command arguments (continued) Parameter and arguments Description [--includemystartuppages true false] Optional parameter. The default setting is true. This parameter only applies when the includeentitiesfromapp parameter is also specified. [--includetransformations true false] Optional parameter. The default setting is true. --username tip_username Mandatory parameter. The user name for a user with the iscadmins role. --password tip_user_password Mandatory parameter. The password for the specified user name. tipcli - Charting Export options: Use the ChartExportPlugin tipcli command to exportdashboard Application Serices Hub chart data. Restriction: When running consolecli.sh bat commands in Tioli Integrated Portal enironments, you must use tipcli.sh/bat instead. That is, the consolecli.sh bat commands replaced the tipcli.sh/bat commands with the release of Dashboard Application Serices Hub. Attention: These instructions assume that you are exporting data from a Tioli Integrated Portal enironment and not a Dashboard Application Serices Hub one. Therefore, the file paths and commands are documented in relation to a Tioli Integrated Portal instance. For example, commands are documented using tipcli instead of consolecli. For Dashboard Application Serices Hub enironments, substitute the tipcli element of the command with consolecli. Note: If you specify additional parameters for the tipcli.bat.sh Export and make a typing error, that is, if you type a parameter incorrectly, or use the incorrect case, then the commands runs as if no parameters were specified and no warning message is displayed. Export [--includecharts ALL NONE dashboard_id1,dashboard_id2] --username tip_username --password tip_user_password Table 33. ChartExportPlugin command arguments Parameter and arguments Description [--includecharts ALL NONE dashboard_id1,dashboard_id2] --username tip_username --password tip_user_password Optional parameter. You can export all charts, no charts, or specify a list of charts to be exported. The default setting is ALL. Note: If you run the Export command using the --includecharts parameter, it must be run by the same user that started the Jazz for Serice Management application serer. Mandatory parameter. The user name for a user with the chartadministrator role. Mandatory parameter. The password for the specified user name. Appendix. Jazz for Serice Management references 175

186 Import consolecli commands consolecli commands for importing Dashboard Application Serices Hub data. Restriction: When running consolecli.sh bat commands in Tioli Integrated Portal enironments, you must use tipcli.sh/bat instead. That is, the consolecli.sh bat commands replaced the tipcli.sh/bat commands with the release of Dashboard Application Serices Hub. Note: If you specify additional parameters for the consolecli.bat.sh Import and make a typing error, that is, if you type a parameter incorrectly, or use the incorrect case, then the commands runs as if no parameters were specified and no warning message is displayed. ListImportPlugins Use the ListImportPlugins command to list all plugins that are aailable to be imported. Import [--includeplugins --excludeplugins plugin1,plugin2] [--settingfile setting_file] [--backupdir backup_dir] --username console_username --password console_user_password Use the Import command to import customization data into a Dashboard Application Serices Hub enironment. If you proide no parameters to the Import command, all custom data is imported by default. Table 34. Import command arguments Parameter and arguments [--includeplugins --excludeplugins plugin1,plugin2] [--settingfile setting_file] [--backupdir backup_dir] --username console_username --password console_user_password Description Optional parameter. You can choose to include or exclude a list of plugins when you run the Import command. Optional parameter. You can specify your import requirements in a properties file instead of specifying your requirements using separate parameters at the command line. Proide a path to the settings file as the argument to the settingfile parameter. On systems running Windows you must use double backslashes characters (\\) when specifying the path to your settings file, for example, C:\\tmp\\import.properties. Command line parameters take precedence oer entries in the settings file. You can specify a directory to sae the backup data during an import operation so that if it is required you can subsequently restore settings. Mandatory parameter. The user name for a user with the iscadmin role. Mandatory parameter. The password for the specified user name. ImportPagePlugin consolecli command: Use the ImportPagePlugin consolecli command to import preiously exported Dashboard Application Serices Hub data. 176 Jazz for Serice Management: Configuration Guide Draft

187 Restriction: When running consolecli.sh bat commands in Tioli Integrated Portal enironments, you must use tipcli.sh/bat instead. That is, the consolecli.sh bat commands replaced the tipcli.sh/bat commands with the release of Dashboard Application Serices Hub. Note: If you specify additional parameters for the consolecli.bat.sh Import and make a typing error, that is, if you type a parameter incorrectly, or use the incorrect case, then the commands runs as if no parameters were specified and no warning message is displayed. Import [--importfile import_file] [--rollback ALL] [--hasupport both true false] --username console_username --password console_user_password Windows Example command: consolecli.bat Import --importfile c:/tmp/extest.zip --username sampleuser --password samplepassword In this example, extest.zip, which is the output an ExportPagePlugin operation, is imported into the target Dashboard Application Serices Hub instance. Table 35. ImportPagePlugin command arguments Parameter and arguments Description [--importfile import_file] Optional parameter. Specifies the path and file name for the data to be imported, for example, c:/tmp/extest.zip. [--rollback ALL] Optional parameter. Use the rollback parameter if you want to restore a Dashboard Application Serices Hub enironment to its pre-import state. You can only roll back an import if you hae made no changes to the enironment since you performed the import. [--hasupport both true false] Optional parameter. You can set this parameter to both, true, orfalse. The setting indicates whether to include load balancing data, the default alue is both. If you set it to false, only non-load balancing data is imported, that is, transformations. If is set to true, only load balancing base data is imported. When it is set to both, both types of data are imported. This parameter can also be used in non-load balanced enironments. If is set to true, only base data is imported. If you set it to false, only non-base data is imported, that is, transformations. Context Menu Serice consolecli commands consolecli commands for working with the Context Menu Serice (CMS). Exporting CMS data There are two menu element types aailable in cms.xml: System menu Menus generated by deploying an application are called system menus. Appendix. Jazz for Serice Management references 177

188 Custom menu Menus added through a Representational State Transfer (REST) serice are called custom menus. The export function migrates only custom launch entries from cms.xml. Exported CMS data includes two files: cms.xml This file when exported, contains all the custom launch entry details from the original cms.xml. The exported cms.xml is formatted slightly different from the original cms.xml in order for it to be imported more easily. naigation.xml Some details for launch entries are stored in naigation.xml, for example, wscrole, wscroletype, and launchtype. The exported naigation.xml contains only details from the original naigation.xml that relate to the custom launch entries exported in cms.xml CMS export command CMSExport --dir export_directory where export_directory is the location where you want the output files to be saed. For example: Windows DASH_HOME\bin\consolecli.bat CMSExport --dir C:\cms_ei Once the command completes, a file called cms.zip is created in the export_directory that you specified. cms.zip contains all the exported CMS data, which can be subsequently imported to another instance of Dashboard Application Serices Hub. Importing CMS data Exported CMS data can be subsequently imported to another Dashboard Application Serices Hub instance. CMS import command CMSImport --username console_username --password console_user_password --dir import_directory Where: --dir import_directory specifies the directory that contains the cms.zip file that was copied from the export_directory on the source Dashboard Application Serices Hub instance. Note: If you omit the --dir argument from the command, you can proide the export_directory path in interactie mode. --username console_username --password console_user_password specifies a alid username and password for thedashboard Application Serices Hub instance. 178 Jazz for Serice Management: Configuration Guide Draft

189 Note: If you omit the --username and --username arguments from the command, you must proide the console_username and console_user_password in interactie mode. For example: Windows DASH_HOME\bin\consolecli.bat CMSImport --dir C:\cms_ei Once the command completes, CMS data is imported into the Dashboard Application Serices Hub enironment and the releant menus are updated. Importing using a properties file You can also optionally use a --settingsfile settings_file properties file with the CMSImport command to create a CMS datasource and update consoleproperties.xml. Additional commands Additional consolecli commands. cmsupdateremoteentries [--username username --password password] (-toremote -fromremote -deleteremote) [-force] Sae system information in the file specified. Table 36. cmsupdateremoteentries command arguments Parameter and arguments Description [--username username --password password] -toremote -fromremote -deleteremote Optional parameters. User name and password for a Dashboard Application Serices Hub user. If you do not proide user name and password details at the command line, you must enter the user name and password in an interactie mode. Optional parameter. Indicates that the update is to occur to the remote data store, that is, the local information is to be written to the remote database. Optional parameter. Indicates that the update is to occur from the remote data store. Any information saed locally is downloaded and updated from the remote database. Optional parameter. Indicates that the launch entries proided by this Dashboard Application Serices Hub instance to the remote database is to be deleted from the database. Additionally, this command preents any further updates from being sent to the remote database. On execution, the cmsupdateremoteentries command with the toremote and force options updates the database and re-enables automatic updates to the remote database. Note: There is no difference between deleteremote with the force option and deleteremote without the force option. Appendix. Jazz for Serice Management references 179

190 Table 36. cmsupdateremoteentries command arguments (continued) Parameter and arguments Description -force Optional parameter. Indicates that any caching or optimization mechanisms for the data should be ignored and that the data should be updated regardless of the state.any existing cached information is discarded. All data in the database is refreshed for the toremote case, including the resource bundles. Version List the ersions of the products and components installed in the enironment. SystemInfo [--outputfile outputfile] Sae system information in the file specified. ITMLogin --hostname hostname --port port --username username --password password [--sericename] ITMLogin is used to configure the ITM Web Serice to connect to the Tioli Enterprise Portal Serer. For example, this command in Windows configures the username and password for a new ITM Web Serice to be added to the Jazz for Serice Management application serer instance. C:\IBM\dash\bin\consolecli.bat ITMLogin --hostname localhost --port username sysadmin --password sysadm1n --sericename ITMWebSerice2 You can use the ITMLogin command to change the hostname, port, username, and password of an existing Tioli Enterprise Portal Serer instance. Changing a configured ITM Web Serice to a different Tioli Enterprise Portal Serer is not supported, because the two portal serers may hae different configurations. If you need to use a different portal serer, you can install another instance of the ITM Web Serice and use this command (along with the -sericename option) to configure. TADDMLogin --hostname hostname [--port port] --username username --password password Log in to the Tioli Application Dependency Discoery Manager. consoleregister command Use the consoleregister command to check for products or components indashboard Application Serices Hub registry. Syntax The consoleregister command is entered in the DASH_HOME/bin directory. The following arguments can be used with the consoleregister command: -isempty Check if the Dashboard Application Serices Hub registry is empty: Linux UNIX DASH_HOME/bin/consoleRegister.sh -isempty Windows DASH_HOME\bin\consoleRegister.bat -isempty -showall List applications from the Dashboard Application Serices Hub registry: 180 Jazz for Serice Management: Configuration Guide Draft

191 Linux UNIX DASH_HOME/bin/consoleRegister.sh -showall Windows DASH_HOME\bin\consoleRegister.bat -showall Registry Serices commands With the Registry Serices commands, you can run arious tasks, such as installation and uninstallation of the Registry Serices database, through the command-line interface (CLI). The CLI operations are entered through a command line where you define the required alues for the parameters. Specific information for each CLI run is defined in a properties file. URL parameters and properties The Registry Serices URL parameters that you pass when you run a CLI command must match the Registry Serices root URL. If you define the public URL in Registry Serices configuration, all URL parameters must match that alue. Otherwise, all URLs must be consistent within the request. When you run a CLI command, such as deleteproider and remapurl, the parameters alues that you pass must match the appserer.host, appserer.port, and appserer.clientauthentication properties alues. For example, if you set the following properties as shown: appserer.host=hostname appserer.port=9086 appserer.clientauthentication=basic The -proiderurl parameter must start with If you set the following properties as shown: appserer.host=hostname appserer.port=9449 appserer.clientauthentication=client-cert The -proiderurl parameter must start by The CLI connects to the serer with the root URL gien by appserer.host, appserer.port, and appserer.clientauthentication properties alues. Therefore, the -proiderurl parameter that you pass in the request to delete Registration Records must match the root URL. Registry Serices finds nothing to delete if the -proiderurl parameter does not match the root URL. If you must use the HTTPS form of the Registry Serices URLs, set the public URL configuration alue for Registry Serices to match that root URL. All URLs in the CLIs must reference that alue. The Registry Serices application uses the Registry_Home\etc\CLI.properties file as the default source of properties. Howeer, you can specify any other path to the properties file for the CLI execution. In this case, you must set the -properties parameter from the command-line interface with the path to the properties file. You set the CLI properties not only for Registry Serices installation, but also for any other CLI command operation. See the CLI properties subsections for the list of required properties. Appendix. Jazz for Serice Management references 181

192 Required properties The Registry Serices CLIs that communicate with the WebSphere Application Serer rely on two properties to connect to Registry Serices. These properties are required in the properties file for you to run the CLIs when either authentication mechanism is set to Registry Serices, Basic or Client-Cert: appserer.user appserer.password Security-related properties All CLIs support the setting of security-related properties that are passed in the CLI.properties file, but only the CLIs that communicate with the WebSphere Application Serer also support the -keystore, -keystorepassword, -keystoretype, -truststore, -truststorepassword, -truststoretype CLI parameters. Passing the properties in the file is considered safer than passing them as CLI parameters. The file can be secured in your file system and cannot be probed by other system users by dumping the list of running processes. Howeer, command-line parameters oerride their respectie properties in the CLI.properties file. The SSL properties are jaax.net.ssl.keystore jaax.net.ssl.keystorepassword jaax.net.ssl.truststore jaax.net.ssl.truststorepassword jaax.net.ssl.keystoretype jaax.net.ssl.truststoretype Attention: The install and uninstall CLI commands must be used for manual installation and uninstallation only. For example, after you configure your Jazz for Serice Management enironment for FIPS, you might want to disable non-ssl ports for IBM DB2. You can then use the uninstall and install commands to manually reinstall the Registry Serices application. By default, you must use Installation Manager to install and uninstall Registry Serices. Setting Registry Serices CLI languages Fix Pack 1 Before you run a Registry Serices command-line interface (CLI) command, you can specify in which language you want to get the command output. About this task Table 37 proides the supported codes and the languages that each one represents. Table 37. Supported language codes for Registry Serices CLI output Supported language codes Language descriptions ar Arabic cs Czech da Danish de German 182 Jazz for Serice Management: Configuration Guide Draft

193 Table 37. Supported language codes for Registry Serices CLI output (continued) Supported language codes el en es fi fr he hr hu it ja ko nb nl pl pt pt_br ro ru sl s th tr zh_cn zh_tw Language descriptions Greek English Spanish Finnish French Hebrew Croatian Hungarian Italian Japanese Korean Norwegian Dutch Polish Portuguese (Portugal) Portuguese (Brazil) Romanian Russian Sloenian Swedish Thai Turkish Chinese Chinese If you run Windows in your enironment, you might hae issues when the characters are rendered in these languages: ar, he, and th. You can choose between two mechanisms to modify the language that is displayed in the output of Registry Serices CLI. One mechanism works across all Jaa Virtual Machine and relies on the FRS_JVM_ARGS enironment ariable. Another mechanism works only with IBM Jaa Virtual Machine and relies on the IBM_JAVA_OPTIONS enironment ariable. Procedure 1. Open the command window. 2. On Windows systems, enter either set IBM_JAVA_OPTIONS="- Duser.language=language_code %IBM_JAVA_OPTIONS%", which applies to IBM JVMonly, or set FRS_JVM_ARGS="-Duser.language=language_code", which applies to all JVM. Appendix. Jazz for Serice Management references 183

194 3. Optional: On Linux systems, enter either export IBM_JAVA_OPTIONS="- Duser.language=language_code $IBM_JAVA_OPTIONS", which applies to IBM JVMonly, or export FRS_JVM_ARGS="-Duser.language=language_code", which applies to all JVM. Example These examples show how you can use set the enironment ariables according to your language definition needs. On Windows systems, set FRS_JVM_ARGS="-Duser.language=pl" On Windows systems, set IBM_JAVA_OPTIONS="-Duser.language=it %IBM_JAVA_OPTIONS%" On Linux systems, export FRS_JVM_ARGS="-Duser.language=fr" On Linux systems,export IBM_JAVA_OPTIONS="-Duser.language=ar $IBM_JAVA_OPTIONS" Updating Registry Serices settings through CLI Use the Registry Serices command-line interface (CLI) to configure Registry Serices. The CLI command uses the alues that are specified in the.properties file during their execution. About this task If you install Registry Serices and the other Serices in separate IBM Installation Manager flows, Installation Manager remoes the alues or the credential properties in the Registry_Home\etc\CLI.properties file for security reasons. Installation Manager also remoes these alues during the installation of the other Serices, if you installed Registry Serices from the Registry Serices CLI. The security policy of your organization might require that the CLI properties file is in a secure location. Registry Serices CLI uses the CLI.properties file in the default location, which is Registry_Home\etc\CLI.properties directory. You can oerride this behaior by using the -properties parameter to specify the secure location of the file. After you decide its location, open the CLI.properties file and edit it. You must specify the database and the application serer credentials by using the alues for the ds.jdbc.user, ds.jdbc.password, appserer.user, and appserer.password properties. Registry Serices CLI requires that appserer.user and appserer.password properties alues are set in the properties file. The CLI uses these alues to connect to the Registry Serices application, when the authentication mechanism is set to Basic. You can run the CLI commands from any location besides the directory where the batch and shell files are located. If you do not run from the directory where those files are located, specify their location in the command line. For example, C:\RegistrySerices\bin\frs.bat config -list. 184 Jazz for Serice Management: Configuration Guide Draft

195 Procedure 1. Open the command window. 2. Call the Registry Serices CLI command that you want. Installation command You can use the install command-line interface (CLI) to install the Registry Serices database and the application serer. Command syntax The install CLI syntax aries according to the enironment in which it is run: frs.bat install -type container db [-properties properties_file]./frs.sh install -type container db [-properties properties_file] Parameters Table 38 lists the parameters that are used with the install CLI and proides their description. Table 38. Parameters used in the install CLI Parameter Value Description -type container This alue defines that the install command must configure an application serer to operate as a Registry Serices serer. You must export the FRS_CLASSPATH to indicate the IBM WebSphere Application Serer.jar file for its admin API, as shown in this example for WebSphere Application Serer V8 WAS_HOME/runtimes/com.ibm.ws.admin.client_8.0.0.jar WAS_HOME/plugins/com.ibm.ws.security.crypto.jar db This alue defines that the install command must deploy the Registry Serices database and install the Resource Shape into a supported relational database management system (RDBMS). -properties properties_file This alue defines that the.properties file must act as the source of the installation properties. This parameter is optional. If you do not specify this parameter, the default REGISTRY_HOME\etc\ CLI.properties file is used as the source of installation properties. Some mandatory installation properties become optional when you install the Registry Serices through the CLI. These properties are ear.file and package.dir. Registry Serices can determine the locations of both files these properties specify based on the location of frs.bat or frs.sh scripts. Howeer, if you specify these properties in the.properties file, they take precedence oer automatic determination. The -type parameter from the install command-line interface defines the Registry Serices installer to be started. Depending on the alue you defined for this parameter, you must set a specific property. Howeer, if these specific properties are not set, the default behaior aoids any failures during the Registry Serices installation process. container If the appserer.type property is not set, the default alue is used instead: WebSphere. If the ear.file property is not set, the configuration found in the Appendix. Jazz for Serice Management references 185

196 properties with the default location of Registry_Home/FRS-container.jar is used instead, which can be deried from Registry_Home/installableApps/ FRS-Websphere.jar. When you install the Registry Serices application with FIPS mode enabled, pass these SSL parameters to specify the certificate to be used for creating a SOAP connection to the WebSphere Application Serer. Table 39 lists the SSL parameters that you can specify when you install Registry Serices with FIPS mode enabled. Table 39. SSL parameters used in the install CLI (FIPS mode enabled) Parameter Value Description -keystore file_name This alue defines the name of the keystore file that contains a certificate for a user that is mapped to one of the roles in theregistry Serices application. There can be multiple certificates. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystore property in the CLI.properties file. -keystorepassword password This alue defines the password for the certificate that is specified in the -keystore parameter. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystorepassword property in the CLI.properties file. 186 Jazz for Serice Management: Configuration Guide Draft

197 Table 39. SSL parameters used in the install CLI (FIPS mode enabled) (continued) Parameter Value Description -truststore file_name This alue defines the name of the truststore file that contains the certificate of the serer that Registry Serices is expected to connect to for processing this CLI. There can be multiple certificates to multiple serers. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststore property in the CLI.properties file. -truststorepassword password This alue defines the password for the certificate that is specified in the -truststore parameter. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststorepassword property in the CLI.properties file. [-keystoretype] type_name This alue defines the keystore type. The default alue for this optional parameter is the keystore.type specified in the jaa.security file of the JDK in use. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystoretype property in the CLI.properties file. Appendix. Jazz for Serice Management references 187

198 Table 39. SSL parameters used in the install CLI (FIPS mode enabled) (continued) Parameter Value Description [-truststoretype] type_name This alue defines the truststore type. The default alue for this optional parameter is the truststore.type specified in the jaa.security file of the JDK in use. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststoretype property in the CLI.properties file. db You can use the db.info.path, db.data.path, and db.txlog.path optional properties to install the database in a custom directory. These properties can be used when the default location has limitations in terms of permission, performance, and disk space. When you install the Registry Serices database with FIPS mode enabled, specify the JDBC connection string in the CLI.properties file by following this format: jdbc:db2://serer:port/dbname:sslconnection=true. Sample frs.bat install -type container -properties C:/etc/container.properties frs.bat install -type db./frs.sh install -type container -properties./frs.sh install -type db Return codes The install command prints a return code when it finishes running so you can hae details about the result achieed. Table 40 proides the return codes that you can get by the end of the install run and their respectie descriptions. Table 40. Return codes of the install command run Return Description code 0 The install command ran the operation successfully. 1 The install command failed to run because of a missing -type parameter. 2 The install command failed to run because of a properties file not found. 3 The install command failed to run because of an inalid -type parameter that is specified in the command line. 4 The install command failed to run because of an installation error. By default, you must use IBM Installation Manager to install Registry Serices. This manual procedure that you can run through the install CLI command is used for installation maintenance only. Do not use it unless strictly directed by the support team. 188 Jazz for Serice Management: Configuration Guide Draft

199 Uninstallation command You use the uninstall command-line interface (CLI) to uninstall the Registry Serices database and the application serer. The db.uninstall.type property specifies the type of database uninstallation that takes place. For information about this property, see Properties for installing the Registry Serices database. Command syntax The uninstall CLI syntax aries according to the enironment in which it is run: frs.bat uninstall -type container db [-properties properties_file]./frs.sh uninstall -type container db [-properties properties_file] Parameters Table 41 lists the parameters that are used with the uninstall CLI and proides their description. Table 41. Parameters used in the uninstall CLI Parameter Value Description -type container This alue defines that the uninstall command must remoe an application serer that operates as a Registry Serices serer. db This alue defines that the uninstall command must uninstall the Registry Serices database and uninstall the Resource Shape from a supported relational database management system (RDBMS). -properties properties_file This alue defines that the.properties file must act as the source of the uninstallation properties. This parameter is optional. If it is not specified, the CLI.properties file is used as the source of uninstallation properties. Some mandatory uninstallation properties become optional when you uninstall Registry Serices through the CLI. These properties are ear.file and package.dir. Both file locations can be determined based on the location of frs.bat or frs.sh scripts. Howeer, if these properties are specified in the.properties file, they take precedence oer automatic determination. When you uninstall the Registry Serices application with FIPS mode enabled, pass these SSL parameters to specify the certificate for creating a SOAP connection to the WebSphere Application Serer: Appendix. Jazz for Serice Management references 189

200 Table 42. SSL parameters used in the uninstall CLI (FIPS mode enabled). Parameter Value Description -keystore file_name This alue defines the name of the keystore file that contains a certificate for a user that is mapped to a Registry Serices role. There can be multiple certificates. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystore property in the CLI.properties file. -keystorepassword password This alue defines the password for the certificate that is specified in the -keystore parameter. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystorepassword property in the CLI.properties file. -truststore file_name This alue defines the name of the truststore file that contains the certificate of the serer to which Registry Serices connects for processing this CLI. There can be multiple certificates to multiple serers. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststore property in the CLI.properties file. 190 Jazz for Serice Management: Configuration Guide Draft

201 Table 42. SSL parameters used in the uninstall CLI (FIPS mode enabled). (continued) Parameter Value Description -truststorepassword password This alue defines the password for the certificate that is specified in the -truststore parameter. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststorepassword property in the CLI.properties file. [-keystoretype] type_name This alue defines the keystore type. The default alue for this optional parameter is the keystore.type specified in the jaa.security file of the JDK in use. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystoretype property in the CLI.properties file. [-truststoretype] type_name This alue defines the truststore type. The default alue for this optional parameter is the truststore.type specified in the jaa.security file of the JDK in use. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststoretype property in the CLI.properties file. Sample frs.bat uninstall -type container -properties C:/etc/container.properties frs.bat uninstall -type db./frs.sh uninstall -type container./frs.sh uninstall -type db Return codes The uninstall command-line interface (CLI) prints a return code at the end of their execution so that the user can hae details about the result achieed. Table 43 on page 192 proides the return codes that can be printed by the end of the uninstall execution and their respectie descriptions. Appendix. Jazz for Serice Management references 191

202 Table 43. Return codes of uninstall command run Return code Description 0 The uninstallation ran successfully. 1 The uninstallation failed to run because of a missing -type parameter. 2 The uninstallation failed to run because of a properties file not found. 3 The uninstallation failed to run because of an inalid -type parameter that is specified in the command line. 4 The uninstallation failed to run because of an uninstallation error. By default, you must use IBM Installation Manager to uninstall Registry Serices. This manual procedure that you can run through the uninstall CLI command is used for uninstallation maintenance only. Do not use it unless strictly directed by the support team. Update command You can use the update command-line interface (CLI) to update the Registry Serices database schema from its preious ersion to a new one. Command syntax The update CLI syntax aries according to the enironment in which it is run: frs.bat update -type container db [-properties properties_file]./frs.sh update -type container db [-properties properties_file] Parameters Table 44 lists the parameters that are used with the update CLI and proides their description. Table 44. Parameters used in the update CLI. Parameter Value Description -type container This alue defines that the update command must update the Registry Serices application in IBM WebSphere Application Serer. You must export FRS_CLASSPATH to indicate the WebSphere Application Serer JAR file for its administratie API, as shown in this example for WebSphere Application Serer V8 WAS_HOME/runtimes/com.ibm.ws.admin.client_8.0.0.jar WAS_HOME/plugins/com.ibm.ws.security.crypto.jar db This alue defines that the update command must update the Registry Serices database that was deployed into an RDBMS to the current release ersion. [-properties] properties_file This alue defines that the.properties file must act as the source of the updating properties. This parameter is optional. If you do not specify this parameter, the default REGISTRY_HOME\etc\ CLI.properties file is used as the source of updating properties. When you update the Registry Serices application with FIPS mode enabled, pass these SSL parameters to specify the certificate to be used for creating a SOAP connection to the WebSphere Application Serer: 192 Jazz for Serice Management: Configuration Guide Draft

203 Table 45. SSL parameters used in the update CLI (FIPS mode enabled). Parameter Value Description -keystore file_name This alue defines the name of the keystore file that contains a certificate for a user that is mapped to a Registry Serices role. There can be multiple certificates. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystore property in the CLI.properties file. -keystorepassword password This alue defines the password for the certificate that is specified in the -keystore parameter. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystorepassword property in the CLI.properties file. -truststore file_name This alue defines the name of the truststore file that contains the certificate of the serer to which Registry Serices connects to for processing this CLI. There can be multiple certificates to multiple serers. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststore property in the CLI.properties file. Appendix. Jazz for Serice Management references 193

204 Table 45. SSL parameters used in the update CLI (FIPS mode enabled) (continued). Parameter Value Description -truststorepassword password This alue defines the password for the certificate that is specified in the -truststore parameter. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststorepassword property in the CLI.properties file. [-keystoretype] type_name This alue defines the keystore type. The default alue for this optional parameter is the keystore.type specified in the jaa.security file of the JDK in use. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystoretype property in the CLI.properties file. [-truststoretype] type_name This alue defines the truststore type. The default alue for this optional parameter is the truststore.type specified in the jaa.security file of the JDK in use. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststoretype property in the CLI.properties file. Sample frs.bat update -type container -properties C:/etc/container.properties./frs.sh update -type db Return codes The update command prints a return code when it finishes running so you can hae details about the result achieed. Table 46 on page 195 proides the return codes that you can get by the end of the update run and their respectie descriptions. 194 Jazz for Serice Management: Configuration Guide Draft

205 Table 46. Return codes of the update command run. Return code Description 0 The update command ran the operation successfully. 1 The update command failed to run because of a missing -type parameter. 2 The update command failed to run because of a properties file not found. 3 The update command failed to run because of an inalid -type parameter that is specified in the command line. 4 The update command failed to run because of an update error. 99 The update command failed to run because the readonly operation mode is actie. This command is used for the installation maintenance only. Do not use it unless strictly directed by the support team. Update application command You can use the update command-line interface (CLI) to update the Registry Serices application. This update process includes updating the application ear file that you deployed on the application serer and modifying the authentication model. The operation that you run through the update CLI command does not update any data source settings or user mapping configuration. The update CLI command modifies the new ersion of the ear archie according to the current installation properties and deploys this ear on the serer. During this process, the CLI uses the old ear archie to check whether the user modified the cleansingrules.xml file currently deployed. This CLI compares the current and the original cleansing rules files to determine whether there is any change. If there is any, the update CLI command issues a warning message and keeps all the changes that are made by the user. Then, it generates a new ear file and updates the Registry Serices application on the serer. Command syntax The update CLI syntax aries according to the enironment in which it is run: frs.bat update -type container [-properties properties_file]./frs.sh update -type container [-properties properties_file] Parameters Table 47 lists the parameters that are used with the update CLI and proides their description. Table 47. Parameters used in the update CLI Parameter Value Description -type container This alue defines that the update command must update the Registry Serices application by deploying a new ear file. Appendix. Jazz for Serice Management references 195

206 Table 47. Parameters used in the update CLI (continued) Parameter Value Description [-properties] properties_file This alue defines that the.properties file must act as the source of the updating properties. This parameter is optional. If you do not specify this parameter, the default REGISTRY_HOME\etc\ CLI.properties file is used as the source of updating properties. This update operation requires these properties to be set in the CLI.properties file: app.name appserer.host appserer.user appserer.password appserer.clientauthentication appserer.was.targets appserer.port The application name that is defined in the app.name property must be deployed in the application serer that is defined in the appserer.host and appserer.port properties. When you update the Registry Serices application with FIPS mode enabled, pass these SSL parameters to specify the certificate to be used for creating a SOAP connection to the WebSphere Application Serer: Table 48. SSL parameters used in the update CLI (FIPS mode enabled) Parameter Value Description -keystore file_name This alue defines the name of the keystore file that contains a certificate for a user that is mapped to a Registry Serices role. There can be multiple certificates. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystore property in the CLI.properties file. -keystorepassword password This alue defines the password for the certificate that is specified in the -keystore parameter. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystorepassword property in the CLI.properties file. 196 Jazz for Serice Management: Configuration Guide Draft

207 Table 48. SSL parameters used in the update CLI (FIPS mode enabled) (continued) Parameter Value Description -truststore file_name This alue defines the name of the truststore file that contains the certificate of the serer to which Registry Serices connects to for processing this CLI. There can be multiple certificates to multiple serers. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststore property in the CLI.properties file. -truststorepassword password This alue defines the password for the certificate that is specified in the -truststore parameter. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststorepassword property in the CLI.properties file. [-keystoretype] type_name This alue defines the keystore type. The default alue for this optional parameter is the keystore.type specified in the jaa.security file of the JDK in use. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystoretype property in the CLI.properties file. Appendix. Jazz for Serice Management references 197

208 Table 48. SSL parameters used in the update CLI (FIPS mode enabled) (continued) Parameter Value Description [-truststoretype] type_name This alue defines the truststore type. The default alue for this optional parameter is the truststore.type specified in the jaa.security file of the JDK in use. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststoretype property in the CLI.properties file. Sample frs.bat update -type container -properties C:/etc/container.properties./frs.sh update -type container Return codes The update command prints a return code when it finishes running so you can hae details about the result achieed. Table 49 proides the return codes that you can get by the end of the update run and their respectie descriptions. Table 49. Return codes of the update command run Return code Description 0 The update command ran the operation successfully. 1 The update command failed to run because of a missing -type parameter. 2 The update command failed to run because of a properties file not found. 3 The update command failed to run because of an inalid -type parameter that is specified in the command line. 4 The update command failed to run because of an update error. 99 Fix Pack 1 The update command failed to run because the readonly operation mode is actie. This command is used for the installation maintenance only. Do not use it unless strictly directed by the support team. Update application data source command You can use the update command-line interface (CLI) to update the data source settings of the Registry Serices application that is up and running. This update operation configures only the data source settings that are defined in the IBM WebSphere Application Serer. It does not affect any other application settings. 198 Jazz for Serice Management: Configuration Guide Draft

209 Fix Pack 1 When you run the update CLI command to apply changes to the data source, you must restart the IBM WebSphere Application Serer. This procedure ensures that Registry Serices takes the new data source settings and makes them effectie. Command syntax The update CLI syntax aries according to the enironment in which it is run: frs.bat update -type container -mode datasource [-properties properties_file]./frs.sh update -type container -mode datasource [-properties properties_file] Parameters Table 50 lists the parameters that are used with the update CLI and proides their description. Table 50. Parameters used in the update CLI Parameter Value Description -type container This alue defines that the update command must update the Registry Serices application by deploying a new ear file. -mode datasource This alue defines that only the update command must update only the data source information of the Registry Serices application. Appendix. Jazz for Serice Management references 199

210 Table 50. Parameters used in the update CLI (continued) Parameter Value Description [-properties] properties_file This alue defines that the.properties file must act as the source of the updating properties. This parameter is optional. If you do not specify this parameter, the default REGISTRY_HOME\etc\ CLI.properties file is used as the source of updating properties. This update operation requires these properties to be set in the CLI.properties file: Fix Pack 1 appserer.host Fix Pack 1 appserer.password Fix Pack 1 appserer.port Fix Pack 1 appserer.user ds.jdbc.classpath ds.jdbc.proider.description ds.jdbc.implclass ds.name ds.jdbc.name ds.jdbc.host ds.jdbc.port ds.jdbc.schema ds.jdbc.fips.mode ds.jdbc.user ds.jdbc.password ds.jdbc.clientreroutealternateserername ds.jdbc.clientreroutealternateportnumber ds.jdbc.retryinteralforclientreroute ds.jdbc.maxretriesforclientreroute ds.jdbc.clientreroutesererlistjndiname ds.jdbc.statementconcentrator ds.jdbc.blockingreadconnectiontimeout You cannot use this CLI command to update the JDBC proider type, which is set through the ds.jdbc.type property. The application name that is defined in the app.name property must be deployed in the application serer that is defined in the appserer.host and appserer.port properties. When you update the Registry Serices application with FIPS mode enabled, pass these SSL parameters to specify the certificate to be used for creating a SOAP connection to the WebSphere Application Serer: 200 Jazz for Serice Management: Configuration Guide Draft

211 Table 51. SSL parameters used in the update CLI (FIPS mode enabled) Parameter Value Description -keystore file_name This alue defines the name of the keystore file that contains a certificate for a user that is mapped to a Registry Serices role. There can be multiple certificates. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystore property in the CLI.properties file. -keystorepassword password This alue defines the password for the certificate that is specified in the -keystore parameter. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystorepassword property in the CLI.properties file. -truststore file_name This alue defines the name of the truststore file that contains the certificate of the serer to which Registry Serices connects to for processing this CLI. There can be multiple certificates to multiple serers. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststore property in the CLI.properties file. Appendix. Jazz for Serice Management references 201

212 Table 51. SSL parameters used in the update CLI (FIPS mode enabled) (continued) Parameter Value Description -truststorepassword password This alue defines the password for the certificate that is specified in the -truststore parameter. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststorepassword property in the CLI.properties file. [-keystoretype] type_name This alue defines the keystore type. The default alue for this optional parameter is the keystore.type specified in the jaa.security file of the JDK in use. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystoretype property in the CLI.properties file. [-truststoretype] type_name This alue defines the truststore type. The default alue for this optional parameter is the truststore.type specified in the jaa.security file of the JDK in use. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststoretype property in the CLI.properties file. Sample frs.bat update -type container -mode datasource -properties C:/etc/container.properties./frs.sh update -type container -mode datasource Return codes The update command prints a return code when it finishes running so you can hae details about the result achieed. Table 52 on page 203 proides the return codes that you can get by the end of the update run and their respectie descriptions. 202 Jazz for Serice Management: Configuration Guide Draft

213 Table 52. Return codes of the update command run Return code Description 0 The update command ran the operation successfully. 1 The update command failed to run because of a missing -type parameter. 2 The update command failed to run because of a properties file not found or inalid properties. 3 The update command failed to run because of an inalid -type parameter that is specified in the command line. 4 The update command failed to run because of an update error. Possible reasons for this failure include the ds.name property is not found or the ds.jdbc.type property is modified. 6 The update command failed to run because of an inalid alue that is set to -mode parameter. 99 Fix Pack 1 The update command failed to run because the readonly operation mode is actie. This command is used for the installation maintenance only. Do not use it unless strictly directed by the support team. Update database command You can use the update command-line interface (CLI) to restore the default cleansing rules and Resource Shape definitions in the database. With this CLI, changes in a new fix pack or drier can be integrated in a new enironment. This command is used for the installation maintenance only. Do not use it unless strictly directed by the Support team. The operation that you run through this update CLI command replaces the default cleansing rules or Resource Shape definitions in the Registry Serices database with the ersion in the distribution image. In the distribution image, the cleansing rules file is in REGISTRY_HOME\etc\ cleansingrules\cleansingrules.xml, and the Resource Shape definitions file is in REGISTRY_HOME\etc\im\shapes. Command syntax The update CLI syntax aries according to the enironment in which it is run: frs.bat update -type db -mode shapes cleansing [-properties properties_file]./frs.sh update -type db -mode shapes cleansing [-properties properties_file] Parameters Table 53 on page 204 lists the parameters that are used with the update CLI and proides their description. Appendix. Jazz for Serice Management references 203

214 Table 53. Parameters used in the database update CLI Parameter Value Description -type db This alue defines that the update command must update the Registry Serices database with the Resource Shape definitions or cleansing rules. -mode shapes cleansing This alue defines that the update command must update either the default Resource Shape definitions (shapes) or the default cleansing rules (cleansing) to match the image ersion. [-properties] properties_file This alue defines that the.properties file must act as the source of the updating properties. This parameter is optional. If you do not specify this parameter, the default REGISTRY_HOME\etc\ CLI.properties file is used as the source of updating properties. This update operation requires these properties to be set in the CLI.properties file: ds.jdbc.drier ds.jdbc.url ds.jdbc.user ds.jdbc.password Sample frs.bat update -type db -mode shapes -properties C:/etc/container.properties./frs.sh update -type db -mode cleansing Return codes The update command prints a return code when it finishes running so you can hae details about the result achieed. Table 54 proides the return codes that you can get by the end of the update run and their respectie descriptions: Table 54. Return codes of the database update command run Return code Description 0 The update command ran the operation successfully. 1 The update command failed to run because of a missing -type parameter. 2 The update command failed to run because of inalid properties or properties file not found. 3 The update command failed to run because of an inalid -type parameter that is specified in the command line. 4 The update command failed to run because of an update error. 5 The update command failed to run because of a missing -mode parameter. 6 The update command failed to run because of an inalid -mode parameter that is specified in the command line. 7 The update command failed to run because of a missing Resource Shape definition on the Registry Serices image. Valid for -mode shapes only. 8 The update command failed to run because of an inalid XML content. Valid for -mode shapes only. 98 Fix Pack 2 The update command failed to run because Registry Serices is unable to determine the current operation mode. 204 Jazz for Serice Management: Configuration Guide Draft

215 Table 54. Return codes of the database update command run (continued) Return code 99 Fix Pack 1 Description The update command failed to run because the readonly operation mode is actie. Rollback command Fix Pack 1 You can use the rollback command-line interface (CLI) to roll back the Registry Serices database schema from one ersion to another. If you must roll back Registry Serices application, use the update CLI command. For example, frs.bat update -type container. Before you run the update CLI, ensure that the EAR file that is deployed in the application serer is from the GA ersion. For more information, see Update application command. Command syntax The rollback CLI syntax aries according to the enironment in which it is run: frs.bat rollback -type db -target.r.m.f [-properties properties_file]./frs.sh rollback -type db -target.r.m.f [-properties properties_file] Parameters Table 55 lists the parameters that are used with the rollback CLI and proides their description. Table 55. Parameters used in the rollback CLI. Parameter Value Description -type db This alue defines that the rollback command must roll back the Registry Serices database that is deployed into a supported RDBMS from one ersion to another. -target.r.m.f This alue defines the ersion, release, and modifier, for example, , of the target runtime or artifacts that Registry Serices leaes after the rollback process completes. [-properties] properties_file This alue defines that the properties file must act as the source of the rollback properties. This parameter is optional. If you do not specify this parameter, the default REGISTRY_HOME\etc\ CLI.properties file is used as the source of updating properties. Sample frs.bat rollback -type db -target properties C:/etc/db.properties./frs.sh rollback -type db -target Appendix. Jazz for Serice Management references 205

216 Return codes The rollback command prints a return code when it finishes running so you can hae details about the result achieed. Table 56 proides the return codes that you can get by the end of the rollback run and their respectie descriptions. Table 56. Return codes of the rollback command. Return code Description 0 The rollback command ran the operation successfully. 1 The rollback command failed to run because of a missing -type parameter. 2 The rollback command failed to run because of a properties file not found. 3 The rollback command failed to run because of an inalid -type parameter that is specified in the command line. 4 The rollback command failed to run because of a rollback error. 98 Fix Pack 2 The rollback command failed to run because Registry Serices is unable to determine the current operation mode. 99 The rollback command failed to run because the readonly operation mode is actie. Configuration command You can use the config command-line interface (CLI) to manage configuration items. Therefore, use this CLI to add the configuration items to the Registry Serices database, to delete, and to list them. Configuration items, also known as CIs, are parameters that you can use to set specific Registry Serices functions. For example, how to set a public URL, the retry-after response, or the operation mode to the application. Command syntax The config CLI syntax aries according to the enironment in which it is run: frs.bat config -set [-file] configitem -delete configitemkey -list [-properties properties_file]./frs.sh config -set [-file] configitem -delete configitemkey -list [-properties properties_file] Parameters Table 57 on page 207 lists the parameters that are used with the config CLI and proides their description. 206 Jazz for Serice Management: Configuration Guide Draft

217 Table 57. Parameters used in the config CLI Parameter Value Description -set [-file] configitem The -set parameter alue defines that the config command must add a configuration item with the format key=alue in the Registry Serices database. In the key=alue format, you can specify multiple alues, and these alues must be comma-separated. You can specify the [-file] optional parameter instead of the -set parameter. When you specify [-file], you must define the path to a text file that contains a list of configuration items to be added to the Registry Serices database. This text file must contain one configuration item at each file. -delete configitemkey This alue defines that the config command must remoe the specified configuration item from the Registry Serices database. -list This parameter requires no alue This alue defines that the config command must return a list of all the configuration items added to the Registry Serices database. [-properties] properties_file This alue defines that the.properties file must act as the source of the configuration properties. This parameter is optional. If you do not specify this parameter, this command uses the default REGISTRY_HOME\etc\CLI.properties file as the source of configuration properties. A mandatory property becomes optional when you configure Registry Serices through the CLI. This property is: package.dir. Registry Serices can determine the location of the file this property specifies based on the location of frs.bat or frs.sh scripts. Howeer, if you specify this property in the.properties file, it takes precedence oer automatic determination. Sample frs.bat config -file C:/etc/config.txt -properties C:/etc/configuration.properties frs.bat config -delete newserialnumber frs.bat config -list -properties Registry_Home/etc/config.properties./frs.sh config -set newserialnumber= /frs.sh config -list Return codes The config command prints a return code when it finishes running so you can hae details of the result achieed. Table 58 proides the return codes that you can get by the end of the config command run and their respectie descriptions. Table 58. Return codes of config command run Return Description code 0 The config command ran the operation successfully. 1 The config command failed to run because of a missing -set -delete -list parameter. 2 The config command failed to run because of an inalid or not found.properties file. 3 The config command failed to run because of an inalid -set -delete parameter that is specified in the command line. 4 The config command failed to run because of it was not able to add or remoe the configuration item to the Registry Serices database. Appendix. Jazz for Serice Management references 207

218 Table 58. Return codes of config command run (continued) Return code 98 Fix Pack 2 Fix Pack 1 99 Description The config command failed to run because Registry Serices is unable to determine the current operation mode. The config command failed to run because the readonly operation mode is actie. Resource analytics command Fix Pack 1 You can use the resourceanalytics command-line interface (CLI) to generate a report statistic of Registration Records and Resource Records information. The general report structure for each resource type contains: 1. Number of Registration Records. 2. For each identification rule: a. The total number of Registration Records that match the identification rule. For example, the Registration Records that hae alues for all the properties that are specified in the identification rule. b. The distribution summary of Registration Records that matches the identification rule among the Resource Records that match the identification rule. c. The total number of Registration Records that match the identification rule and that are associated to a Resource Record that also matches the identification rule. d. The three most common identification rule alues. e. The three most common inalidated identification rule alues, if any. 3. The three most common identification rule alues for the resource type. 4. The three most common inalidated identification rule alues for the resource type, if any. 5. The three most common inalidated property alues for the resource type, if any. For this report, only sets of alues for all properties in the identification rule are taken into account. Property alues of resource types whose URL corresponds to a resource that Registry Serices knows hae their Resource Records URIs printed in the report. This example shows an output that the resourceanalytics command generates in plain text format: -- crt:sereraccesspoint (crt:portnumber + crt:ipaddress) = 125 records -- crt:sereraccesspoint (crt:portnumber + crt:ipaddress) ---- number of registration records matching this naming rule = number of registration records found in a resource record matching this naming rule, min/ag/max=1/1/ number of registration records matching this naming rule that are associated to a resource record that also matches this naming rule = number of resource records matching this naming rule = Most common alues for this naming rule: crt:ipaddress=resource{oslc-registry/oslc/resources/ },crt:portnumber=80 1 registration records crt:ipaddress=resource{oslc-registry/oslc/resources/ },crt:portnumber= registration records 208 Jazz for Serice Management: Configuration Guide Draft

219 crt:ipaddress= 82B33D256C32381EAE29A629EA2F45DB,crt:portNumber= registration records ---- Most common alues for the resource type: crt:ipaddress=resource{oslc-registry/oslc/resources/ },crt:portnumber=80 1 registration records crt:ipaddress=resource{oslc-registry/oslc/resources/ },crt:portnumber= registration records crt:ipaddress= 82B33D256C32381EAE29A629EA2F45DB,crt:portNumber= registration records - crt:computersystem = 2 records -- crt:computersystem (crt:serialnumber + crt:model + crt:manufacturer) ---- number of registration records matching this naming rule = number of registration records found in a resource record matching this naming rule, min/ag/max=1/1/ number of registration records matching this naming rule that are associated to a resource record that also matches this naming rule = number of resource records matching this naming rule = Most common alues for this naming rule: crt:manufacturer=ibm,crt:model=tp400,crt:serialnumber= registration records crt:manufacturer=ibm,crt:model=tp500,crt:serialnumber= registration records -- crt:computersystem (crt:systemboarduuid) ---- number of registration records matching this naming rule = number of registration records found in a resource record matching this naming rule, min/ag/max=1/1/ number of registration records matching this naming rule that are associated to a resource record that also matches this naming rule = number of resource records matching this naming rule = Most common alues for this naming rule: crt:systemboarduuid=a1b2c3d4-e5f6 2 registration records ---- Most common inalidated alues for this naming rule: crt:systemboarduuid=a1b2c3d4-e5f6 1 registration records ---- Most common alues for the resource type: crt:systemboarduuid=a1b2c3d4-e5f6 2 registration records crt:manufacturer=ibm,crt:model=tp400,crt:serialnumber= registration records ---- Most common inalidated alues for the resource type: crt:systemboarduuid=a1b2c3d4-e5f6 1 registration records ---- Most common inalidated properties for the resource type: crt:systemboarduuid=a1b2c3d4-e5f6 1 registration records This example is an output that the resourceanalytics command generates in XML format: <?xml ersion="1.0" encoding="utf-8"?><resourceanalytics> <ResourceType type="crt:sereraccesspoint"> <Count description="number of registration records" alue="125"/> <NamingRule priority="1" rule="crt:portnumber + crt:ipaddress"> <Count description="number of registration records matching this naming rule" alue="125"/> <Count description="number of registration records found in a resource record matching this naming rule, min / ag / max" alue="1 / 1/ 1"/> <Count description="number of registration records matching this naming rule that are associated to a resource record that also matches this naming rule" alue="125"/> <Count description="number of resource records matching this naming rule" alue="125"/> <TopCommonValues> <TopCommonValue occurences="1" rank="1" alues="crt:ipaddress= RESOURCE{oslc-registry/oslc/resources/ },crt:portNumber=80"/> <TopCommonValue occurences="1" rank="2" alues="crt:ipaddress= RESOURCE{oslc-registry/oslc/resources/ },crt:portNumber=21018"/> <TopCommonValue occurences="1" rank="3" alues="crt:ipaddress= 82B33D256C32381EAE29A629EA2F45DB,crt:portNumber=10864"/> </TopCommonValues> </NamingRule> <TopCommonValues> <TopCommonValue occurences="1" rank="1" alues="crt:ipaddress= RESOURCE{oslc-registry/oslc/resources/ },crt:portNumber=80"/> <TopCommonValue occurences="1" rank="2" alues="crt:ipaddress= RESOURCE{oslc-registry/oslc/resources/ },crt:portNumber=21018"/> <TopCommonValue occurences="1" rank="3" alues="crt:ipaddress= 82B33D256C32381EAE29A629EA2F45DB,crt:portNumber=10864"/> </TopCommonValues> </ResourceType> <ResourceType type="crt:computersystem"> <Count description="number of registration records" alue="2"/> <NamingRule priority="4" rule="crt:serialnumber + crt:model + crt:manufacturer"> <Count description="number of registration records matching this naming rule" alue="2"/> <Count description="number of registration records found in a resource record matching this naming rule, min / ag / max" alue="1 /1/1"/> <Count description="number of registration records matching this naming rule that are associated to a resource Appendix. Jazz for Serice Management references 209

220 record that also matches this naming rule" alue="2"/> <Count description="number of resource records matching this naming rule" alue="2"/> <TopCommonValues> <TopCommonValue occurences="1" rank="1" alues="crt:manufacturer=ibm, crt:model=tp400,crt:serialnumber= "/> <TopCommonValue occurences="1" rank="2" alues="crt:manufacturer=ibm, crt:model=tp500,crt:serialnumber= "/> </TopCommonValues> </NamingRule> <NamingRule priority="5" rule="crt:systemboarduuid"> <Count description="number of registration records matching this naming rule" alue="2"/> <Count description="number of registration records found in a resource record matching this naming rule, min / ag / max" alue="1 /1/1"/> <Count description="number of registration records matching this naming rule that are associated to a resource record that also matches this naming rule" alue="1"/> <Count description="number of resource records matching this naming rule" alue="1"/> <TopCommonValues> <TopCommonValue occurences="2" rank="1" alues="crt:systemboarduuid= a1b2c3d4-e5f6"/> </TopCommonValues> <TopInalidatedValues> <TopInalidatedValue occurences="1" rank="1" alues="crt:systemboarduuid= a1b2c3d4-e5f6"/> </TopInalidatedValues> </NamingRule> <TopCommonValues> <TopCommonValue occurences="2" rank="1" alues="crt:systemboarduuid= a1b2c3d4-e5f6"/> <TopCommonValue occurences="1" rank="3" alues="crt:manufacturer=ibm, crt:model=tp400, crt:serialnumber= "/> </TopCommonValues> <TopInalidatedValues> <TopInalidatedValue occurences="1" rank="1" alues="crt:systemboarduuid= a1b2c3d4-e5f6"/> </TopInalidatedValues> <TopInalidatedProperties> <TopInalidatedProperty occurences="1" rank="1" alues="crt:systemboarduuid= a1b2c3d4-e5f6"/> </TopInalidatedProperties> </ResourceType> Command syntax The resourceanalytics CLI syntax aries according to the enironment in which it is run: frs.bat resourceanalytics [-help] [-minaliasesthreshold alias_threshold] [-outputtype xml plain] [-file] output_filename] [-properties properties_file]./frs.sh resourceanalytics [-help] [-minaliasesthreshold alias_threshold] [-outputtype xml plain] -file output_filename] [-properties properties_file] Parameters Table 59 lists the parameters that you can use with the resourceanalytics CLI and proides their description. Table 59. Parameters used in the resourceanalytics CLI Parameter Value Description [-help] [-minaliases Threshold] This parameter requires no alue alias_threshold This parameter displays all alid parameters for running the resourceanalytics command. This parameter alue defines the minimum number of Registration Records that are associated to a Resource Record that makes the corresponding identification rule eligible to be reported in the output. 210 Jazz for Serice Management: Configuration Guide Draft

221 Table 59. Parameters used in the resourceanalytics CLI (continued) Parameter Value Description [-outputtype] xml plain This parameter alue defines the format in which the resourceanalytics command must return the output report. Valid alues are XML and plain, which is the default alue. [-file] output_filename This parameter alue defines the name of the file where the output is written to. This file must not exist for you to run the resourceanalytics command successfully. [-properties] properties_file This alue defines that the.properties file must act as the source of the resource analytics properties. This parameter is optional. If you do not specify this parameter, this command uses the default REGISTRY_HOME\etc\CLI.properties file as the source of resource analytics properties. A mandatory property becomes optional when you configure Registry Serices through the CLI. This property is package.dir. Registry Serices can determine the location of the file this property specifies based on the location of frs.bat or frs.sh scripts. Howeer, if you specify this property in the.properties file, it takes precedence oer automatic determination. Sample frs.bat resourceanalytics -file C:/etc/resourceanalytics.txt -properties C:/etc/ranalytics.properties frs.bat resourceanalytics -help frs.bat resourceanalytics -outputtype XML -properties Registry_Home/etc/ranalytics.properties./frs.sh resourceanalytics -minaliasthreshold 20./frs.sh resourceanalytics -help Return codes The resourceanalytics command prints a return code when it finishes running so you can hae details of the result achieed. Table 60 proides the return codes that you can get by the end of the resourceanalytics command run and their respectie descriptions. Table 60. Return codes of resourceanalytics command run Return Description code 0 The resourceanalytics command ran the operation successfully. 1 The resourceanalytics command failed to run because of a properties file not found or an inalid property. 2 The resourceanalytics command failed to run because the -minaliasesthreshold parameter alue is not a number or it is a negatie number. 3 The resourceanalytics command failed to run because the -outputtype parameter alue is inalid. Appendix. Jazz for Serice Management references 211

222 Table 60. Return codes of resourceanalytics command run (continued) Return code Description 4 The resourceanalytics command failed to run because the file that you specified as the -file parameter alue already exists. Retry attempts configuration command Fix Pack 1 You can use the config command-line interface (CLI) with the reprocess.retryattempts to set the number of times that Registry Serices tries to process again the Registration Records that originated conflicting operations to modify Resource Records. You use the reprocess.retryattempts parameter only for batch reconciliation operations. After Registry Serices processes a batch operation request, it recomputes the reconciled state of Resource Records. If this operation tries to modify a Resource Record under modification by another operation, Registry Serices stores the Registration Record that originated the request in a queue. When there are no more Resource Records to be processed, Registry Serices reisits the queue and tries to process the Registration Records again. The application remoes from the queue Registration Records successfully processed. You can specify the number of times that Registry Serices attempts to process the Registration Records in the queue through the reprocess.retryattempts configuration parameter. By default, the application tries to reprocess each Registration Record in the queue for three times. Command syntax The config CLI syntax aries according to the enironment in which it is run: frs.bat config -set -delete -list reprocess.retryattempts=number [-properties properties_file]./frs.sh config -set -delete -list reprocess.retryattempts=number [-properties properties_file] Parameters Table 61 lists the parameters that are used with the config CLI and proides their description. Table 61. Parameters used in the config CLI Parameter Value Description -set reprocess.retryattempts= number This alue defines that the config command must set the number of times that Registry Serices tries to process again the Registration Records that conflicted with concurrent operations to modify Resource Records. The default alue for this parameter is Jazz for Serice Management: Configuration Guide Draft

223 Table 61. Parameters used in the config CLI (continued) Parameter Value Description -delete reprocess.retryattempts This alue defines that the config command must remoe the number of attempts that is set in the enironment. -list This parameter requires no alue This alue defines that the config command must return a list of all configuration items that are set in the enironment. [-properties] properties_file This alue defines that the.properties file must act as the source of the configuration properties. This parameter is optional. If you do not specify this parameter, this command uses the default REGISTRY_HOME\etc\CLI.properties file as the source of configuration properties. A mandatory property becomes optional when you configure Registry Serices through the CLI. This property is package.dir. Registry Serices can determine the location of the file this property specifies based on the location of frs.bat or frs.sh scripts. Howeer, if you specify this property in the.properties file, it takes precedence oer automatic determination. Sample frs.bat config -set reprocess.retryattempts=5 -properties C:/etc/configuration.properties frs.bat config -delete reprocess.retryattempts./frs.sh config -set reprocess.retryattempts=8./frs.sh config -list Return codes The config command prints a return code when it finishes running so you can hae details of the result achieed. Table 62 proides the return codes that you can get by the end of the config command run and their respectie descriptions. Table 62. Return codes of config command run Return code Description 0 The config command ran the operation successfully. 1 The config command failed to run because of a missing -set -delete -list parameter. 2 The config command failed to run because of an inalid or not found.properties file. 3 The config command failed to run because of an inalid -set -delete parameter that is specified in the command line. 4 The config command failed to run because of it was not able to add or remoe the configuration item to the Registry Serices database. Fix Pack 2 98 The config command failed to run because Registry Serices is unable to determine the current operation mode. 99 The config command failed to run because the readonly operation mode is actie. Retry-After response configuration command You can use the config command-line interface (CLI) to set the required alue for the Retry-After response header. This header indicates how long the serice is expected to be unaailable to the requesting client. Appendix. Jazz for Serice Management references 213

224 If you want to specify the amount of time to try sending the request again after you receie an HTTP status code 503 (Serice Unaailable), use the response.retryafter parameter. This amount of time is based on the time that is estimated for Registry Serices to complete one of its concurrent processes. Command syntax The config CLI syntax aries according to the enironment in which it is run: frs.bat config -set -delete -list response.retryafter=time [-properties properties_file]./frs.sh config -set -delete -list response.retryafter=time [-properties properties_file] Parameters Table 63 lists the parameters that are used with the config CLI and proides their description. Table 63. Parameters used in the config CLI for setting the retryafter alue Parameter Value Description The -set parameter alue must always be response.retryafter=time. -set response.retryafter=time The response.retryafter specifies the amount of time, in seconds, that you can try sending the request again after you receie an HTTP status code 503 (Serice Unaailable). The default alue for this parameter is 2 seconds. The -delete parameter alue must always be set to response.retryafter. -delete -list response.retryafter This parameter requires no alue This parameter defines that the config command must delete the Retry-After alue preiously created. The -list parameter defines that the config command must return a list of all the existing URLs in the Registry Serices database. [-properties] properties_file This alue defines that the.properties file must act as the source of the configuration properties. This parameter is optional. If you do not specify this parameter, this command uses the CLI.properties file as the source of configuration properties. A mandatory property becomes optional when you configure Registry Serices through the CLI. This property is: package.dir. Registry Serices can determine the location of the file this property specifies based on the location of frs.bat or frs.sh scripts. Howeer, if you specify this property in the.properties file, it takes precedence oer automatic determination. Sample frs.bat config -set response.retryafter=10 frs.bat config -delete response.retryafter=5 -properties Registry_Home/etc/ default/config.properties./frs.sh config -set response.retryafter=20./frs.sh config -list 214 Jazz for Serice Management: Configuration Guide Draft

225 Return codes The config command prints a return code when it finishes running so you can hae details about the result achieed. Table 64 proides the return codes that you can get by the end of the config command run and their respectie descriptions. Table 64. Return codes of config command run Return Description code 0 The config command ran the operation successfully. 1 The config command failed to run because of a missing -set -delete -list parameter. 2 The config command failed to run because of an inalid or not found.properties file. 3 The config command failed to run because of an inalid -set -delete parameter alue that is specified in the command line. 4 The config command failed to run because of an error while you were adding or remoing the Retry-After alue. Fix Pack 1 99 The config command failed to run because the readonly operation mode is actie. Operation mode configuration command You can use the config command-line interface (CLI) not only to manage configuration items and set the public URL, but also to define the operation mode of the Registry Serices application. Fix Pack 1 In this case, the config CLI parameters alue must always be operation.mode=mode, where mode can be normal, reconciliation, orreadonly. Fix Pack 2 By default, if Registry Serices is not able to determine its current operation mode, the application blocks all requests that might cause changes to the database. Normal mode This mode is the default state of the Registry Serices application. Fix Pack 1 When the application is in normal mode, it works without any specific restriction. Reconciliation mode This mode is a special state of the Registry Serices application, which you use to coney maintenance tasks, such as Resource Shape update. The reconciliation mode aims at disabling requests to the application that might return unreliable results. Therefore, this mode blocks the read access to resources, so you do not see inconsistent data. The Resource Shape update is a good example of such requests. The administrator might be required to send multiple Resources Shape update requests before the records already registered actually reconcile. In this case, the reconciliation might also be an operation that takes a large amount of time to be complete. And until the reconciliation is complete, any query for Resource Records can return unreliable results. Appendix. Jazz for Serice Management references 215

226 Fix Pack 1 Therefore, setting the Registry Serices application to the reconciliation mode preents any query or retrieal operation to return inconsistent and unreliable results. While in reconciliation mode, your access to Resource Records is limited. You can retriee Registration Records only. Read-only mode This mode is a special state of Registry Serices, which you use to disable all operations of the application serers that change the database. Therefore, you set the Registry Serices application to readonly mode to safely aoid operations that can corrupt data while the application serers are under maintenance. For example, when the application in readonly mode, it preents any create, update, or delete operation to return inconsistent and unreliable results. Command syntax The config CLI syntax for setting the operation mode of the Registry Serices application aries according to the enironment in which it is run: frs.bat config -set -delete -list operation.mode=mode [-properties properties_file]./frs.sh config -set -delete -list operation.mode=mode [-properties properties_file] Parameters Table 65 lists the parameters that are used with the config CLI and proides their description. Table 65. Parameters used in the config CLI for setting the operation mode Parameter Value Description -set -delete -list operation.mode=mode operation.mode This parameter requires no alue The -set parameter alue must always be operation.mode=mode, where mode can be normal, reconciliation, or readonly. This parameter defines that the config command must set the operation mode of the Registry Serices application according to the specified alue. The -delete parameter alue must always be set to operation.mode. This parameter defines that the config command must remoe the current operation mode alue. For deleting the Registry Serices operation mode, you are not required to specify the mode alue. The -list parameter defines that the config command must return the current operation mode of the Registry Serices application. 216 Jazz for Serice Management: Configuration Guide Draft

227 Table 65. Parameters used in the config CLI for setting the operation mode (continued) Parameter Value Description [-properties] properties_file This alue defines that the.properties file must act as the source of the configuration properties. This parameter is optional. If you do not specify this parameter, this command uses the CLI.properties file as the source of configuration properties. A mandatory property becomes optional when you configureregistry Serices through the CLI. This property is package.dir. Registry Serices can use the location of the frs.bat or frs.sh scripts to determine the location of the file this property specifies. Howeer, if you specify this property in the.properties file, it takes precedence oer automatic determination. Sample Fix Pack 1 frs.bat config -set operation.mode=reconciliation frs.bat config -set operation.mode=readonly frs.bat config -delete operation.mode./frs.sh config -set operation.mode=normal./frs.sh config -list Return codes The config command prints a return code when it finishes running so you can hae details about the result achieed. Table 66 proides the return codes that you can get by the end of the config command run and their respectie descriptions. Table 66. Return codes of config command run Return Description code 0 The config command ran the operation successfully. 1 The config command failed to run because of a missing -set -delete -list parameter. 2 The config command failed to run because of an inalid or not found.properties file. 3 The config command failed to run because of an inalid -set -delete parameter alue that is specified in the command line. 4 The config command failed to run because of an error while setting, resetting or remoing the operation mode of the Registry Serices application. Fix Pack 2 98 Fix Pack 1 99 The config command failed to run because Registry Serices is unable to determine the current operation mode. The config command failed to run because the readonly operation mode is actie. The Registry Serices application checks the operation mode for alidation. If this operation mode is inalid, the application does not set it and displays an error message. Fix Pack 1 If Registry Serices is in read-only mode and you send an HTTP PUT, POST, or DELETE request, you get the HTTP status code 503 (Serice Unaailable). Appendix. Jazz for Serice Management references 217

228 Transaction isolation configuration command You can use the config command-line interface (CLI) not only to manage configuration items, but also to configure the transaction isolation method. Registry Serices is able to process concurrent requests. In this multiprocess scenario, to aoid any data inconsistency, Registry Serices must ensure that only one request can access that data at a time. Registry Serices can store the locked data on either the memory or the database. When there are multiple Registry Serices running instances, and in different JVM, the data is stored in the database. When there is only one Registry Serices running instance, the use of database lock mechanism is discouraged because there can be performance loss. The lock mechanism to configure the transaction isolation is set through the appserer.transaction.isolation parameter. Valid alues for this parameter are memory and database. Command syntax The config CLI syntax aries according to the enironment in which it is run: frs.bat config -set -delete -list appserer.transaction.isolation=memory database [-properties properties_file]./frs.sh config -set -delete -list appserer.transaction.isolation=memory database [-properties properties_file] Parameters Table 67 lists the parameters that are used with the config CLI and proides their description. Table 67. Parameters used in the config CLI for setting the transaction isolation property Parameter Value Description -set memory database The -set parameter alue must always be appserer.transaction.isolation=memory database. This parameter defines that the config command must set where Registry Serices locks the data to aoid inconsistency while concurrent requests are running. -delete appserer.transaction.isolation The -delete parameter alue must always be set to appserer.transaction.isolation. This parameter defines that the config command must delete the transaction isolation method preiously created. -list This parameter requires no alue The -list parameter defines that the config command must return a list of all the existing transaction isolation methods. 218 Jazz for Serice Management: Configuration Guide Draft

229 Table 67. Parameters used in the config CLI for setting the transaction isolation property (continued) Parameter Value Description [-properties] properties_file This alue defines that the.properties file must act as the source of the configuration properties. This parameter is optional. If you do not specify this parameter, this command uses the CLI.properties file as the source of configuration properties. A mandatory property becomes optional when you configure Registry Serices through the CLI. This property is: package.dir. Registry Serices can determine the location of the file this property specifies based on the location of frs.bat or frs.sh scripts. Howeer, if you specify this property in the.properties file, it takes precedence oer automatic determination. Sample frs.bat config -file appserer.transaction.isolation=database -properties C:/etc/configuration.properties frs.bat config -delete appserer.transaction.isolation./frs.sh config -set appserer.transaction.isolation=memory./frs.sh config -list Return codes The config command prints a return code when it finishes running so you can hae details about the result achieed. Table 68 proides the return codes that you can get by the end of the config command run and their respectie descriptions. Table 68. Return codes of config command run Return code Description 0 The config command ran the operation successfully. 1 The config command failed to run because of a missing -set -delete -list parameter. 2 The config command failed to run because of an inalid or not found.properties file. 3 The config command failed to run because of an inalid -set -delete parameter that is specified in the command line. 4 The config command failed to run because of an error while you are adding or remoing the transaction isolation method. Fix Pack 2 98 Fix Pack 1 99 The config command failed to run because Registry Serices is unable to determine the current operation mode. The config command failed to run because the readonly operation mode is actie. Serice Proider deletion command You can use the deleteproider command-line interface (CLI) to delete all the resources that are associated with a particular Serice Proider. With this CLI, you delete all the records, the reconciled resources, and the proider entry in the specified Proider Registry. Only users that are mapped to the RegistryAdminRole can run this CLI command. Appendix. Jazz for Serice Management references 219

230 Command syntax The deleteproider CLI syntax aries according to the enironment in which it is run: frs.bat deleteproider -proiderurl url [-keystore file_path -keystorepassword password -truststore file_path -truststorepassword password] [-keystoretype type_name] [-truststoretype type_name] [-properties properties_file]./frs.sh deleteproider -proiderurl url [-keystore file_path -keystorepassword password -truststore file_path -truststorepassword password] [-keystoretype type_name] [-truststoretype type_name] [-properties properties_file] Parameters Table 69 lists the parameters that are used with the deleteproider CLI and proides their description. Table 69. Parameters used in the deleteproider CLI Parameter Value Description -proiderurl url This alue defines the name of the Serice Proider to be deleted. [-keystore] file_path This alue defines the name of the keystore file that contains a certificate for a user that is mapped to a Registry Serices role. There can be multiple certificates. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystore property in the CLI.properties file. [-keystorepassword] password This alue defines the password for the certificate that is specified in the -keystore parameter. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystorepassword property in the CLI.properties file. [-truststore] file_path This alue defines the name of the truststore file that contains the certificate of the serer to which Registry Serices connects for processing this CLI. There can be multiple certificates to multiple serers. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststore property in the CLI.properties file. [-truststorepassword] password This alue defines the password for the certificate that is specified in the -truststore parameter. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststorepassword property in the CLI.properties file. [-keystoretype] type_name This alue defines the keystore type. The default alue for this optional parameter is the keystore.type specified in the jaa.security file of the JDK in use. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystoretype property in the CLI.properties file. [-truststoretype] type_name This alue defines the truststore type. The default alue for this optional parameter is the truststore.type specified in the jaa.security file of the JDK in use. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststoretype property in the CLI.properties file. 220 Jazz for Serice Management: Configuration Guide Draft

231 Table 69. Parameters used in the deleteproider CLI (continued) Parameter Value Description [-properties] properties_file This alue defines that the.properties file must act as the source of the delete proider properties. This parameter is optional. If you do not specify this parameter, the CLI.properties file is used as the source of delete proider properties. The properties that are required for deleting the Serice Proider are: appserer.host; appserer.port; appserer.user; and appserer.password, which are also proided for Registry Serices installation purposes. If you do not define any of the certificate parameters alues (keystore, keystorepassword, truststore and truststorepassword), the Registry Serices uses the appserer.user and appserer.password properties alues and assumes the BASIC authentication mechanism for connecting to the serer. If you define all the required parameter alues, Registry Serices uses the CLIENT-CERT authentication mechanism for connecting to the serer. If you define the required parameter alues partially, then this CLI does not connect to Registry Serices and fails to proceed with your request. For parameter alues defined by path and file name, you must take an additional action according to the operating system in use: On Windows systems: if the path and the file name include a space character, enclose the entire path alue with double quotation marks. On Linux systems: if the path and the file name include a space character, escape this character with a back slash. Sample frs.bat deleteproider -proiderurl -keystore C:\Program Files\IBM\Jaa\keycertificate.jks -keystorepassword truststore C:\Program Files\IBM\Jaa\trustcert.jks -truststorepassword properties C:\Registry Serices\etc\delproider.properties./frs.sh deleteproider -proiderurl -keystore /opt/ibm/jaa/keycertificate.jks -keystorepassword truststore /opt/ibm/jaa/trustcert.jks -truststorepassword keystoretype JKS Return codes The deleteproider command prints a return code when it finishes running so you can hae details about the result achieed. Table 70 proides the return codes that you can get by the end of the deleteproider run and their respectie descriptions. Table 70. Return codes of the deleteproider command run Return code Description 0 The deleteproider command ran the operation successfully. 1 The deleteproider command failed to run because of a missing required parameter or an inalid parameter alue. 2 The deleteproider command failed to run because of a properties file not found or properties alues inalid. 3 The deleteproider command failed to run because of an internal error that is logged in the CLI log files. Appendix. Jazz for Serice Management references 221

232 Table 70. Return codes of the deleteproider command run (continued) Return code Description 4 The deleteproider command failed to run because of a failure to connect to the automation batch URL by using the authentication details. HTTP status code 401 (Unauthorized) or 403 (Forbidden). 5 The deleteproider command failed to run because of the impossibility of accessing the automation batch URL. HTTP status code 404 (Not Found). 6 The deleteproider command failed to run because of the impossibility of accessing the automation batch URL. HTTP status code 500 (Internal Serer Error). 7 The deleteproider command failed to delete the Serice Proider because not all Registration Records or reconciled resources of that Serice Proider were deleted. The command can also fail to delete the Serice Proider after successfully deleting the Registration Records or reconciled resources of that particular Serice Proider. HTTP status code 400 (Bad Request). Public URL configuration command You can use the config command-line interface (CLI) not only to manage configuration items, but also to set the public URL as a configuration alue. In this case, the config CLI parameters alue must always be public.url=url. Command syntax The config CLI syntax for setting the public URL aries according to the enironment in which it is run: frs.bat config -set -delete -list public.url=url [-properties properties_file]./frs.sh config -set -delete -list public.url=url [-properties properties_file] Parameters Table 71 lists the parameters that are used with the config CLI and proides their description. Table 71. Parameters used in the config CLI for setting the public URL Parameter Value Description The -set parameter alue must always be public.url=url. You can set only a single public URL. -set public.url=url The public URL specifies a URL that is different from the root URL. The root URL is composed by the hostname:port where you deployed the Registry Serices application serer. This parameter defines that the config command must set the public URL according to the specified alue (URL), where the URL is composed by protocol, root URL and serer port number. For example, if the protocol is https, the root URL is jazz-registry and the serer port is 8080, the public URL is Jazz for Serice Management: Configuration Guide Draft

233 Table 71. Parameters used in the config CLI for setting the public URL (continued) Parameter Value Description -delete -list public.url This parameter requires no alue The -delete parameter alue must always be set to public.url. To delete the public URL, you are not required to specify this URL. This parameter defines that the config command must delete the public URL preiously created. The -list parameter defines that the config command must return a list of all the existing URLs in the Registry Serices database. [-properties] properties_file This alue defines that the.properties file must act as the source of the configuration properties. This parameter is optional. If you do not specify this parameter, this command uses the CLI.properties file as the source of configuration properties. A mandatory property becomes optional when you configure Registry Serices through the CLI. This property is: package.dir. Registry Serices can determine the location of the file this property specifies based on the location of frs.bat or frs.sh scripts. Howeer, if you specify this property in the.properties file, it takes precedence oer automatic determination. Sample frs.bat config -set public.url= frs.bat config -delete public.url -properties Registry_Home/etc/ default/config.properties./frs.sh config -set public.url= config -list Return codes The config command prints a return code when it finishes running so you can hae details about the result achieed. Table 72 proides the return codes that you can get by the end of the config command run and their respectie descriptions. Table 72. Return codes of config command run Return code Description 0 The config command ran the operation successfully. 1 The config command failed to run because of a missing -set -delete -list parameter. 2 The config command failed to run because of an inalid or not found.properties file. 3 The config command failed to run because of an inalid -set -delete parameter alue that is specified in the command line. 4 The config command failed to run because of an error while it was adding or remoing the public URL to the Registry Serices database. Fix Pack 2 98 Fix Pack 1 99 The config command failed to run because Registry Serices is unable to determine the current operation mode. The config command failed to run because the readonly operation mode is actie. Appendix. Jazz for Serice Management references 223

234 If the URLs returned in your queries do not contain the fully qualified serer name, you can use the config command to oerride this behaior. Use the public URL configuration command to set the serer name with the fully qualified name. Run frs config -set public.url=url, where URL is the fully qualified serer name. For example, frs.bat config -set public.url= jazzsm.somelab.locale.ibm.com:8090. Registry Serices checks the proided URL for alidation: If this URL is inalid, the application does not set it in the database and displays an error message. If this URL is alid, but unreachable, then the application sets it in the database and displays a warning message. Remap URL command You can use the remapurl command-line interface (CLI) to update URLs stored in the Registry Serices database when a Serice Proider record is rehosted or there is a URL change. This change applies to either Serice Proider record or Registration Record URLs. Command syntax The remapurl CLI syntax aries according to the enironment in which it is run: frs.bat remapurl -registrytype proider resource [-filterrule query_string] -patternrule regular_expression -replacementvalue URL_replacement [-keystore file_name_path] [-keystorepassword password] [-truststore file_name_path] [-truststorepassword password] [-keystoretype type_name] [-truststoretype type_name] [-properties properties_file]./frs.sh remapurl -registrytype proider resource [-filterrule query_string] -patternrule regular_expression -replacementvalue URL_replacement [-keystore file_name_path] [-keystorepassword password] [-truststore file_name_path] [-truststorepassword password] [-keystoretype type_name] [-truststoretype type_name] [-properties properties_file] Parameters Table 73 lists the parameters that are used with the remapurl CLI and proides their description. Table 73. Parameters used in the remapurl CLI Parameter Value Description -registrytype proider resource This alue defines whether the batch operation is to be run oer the Proider Registry (proider) or the Resource Registry (resource). [-filterrule] query_string This optional alue defines the filter rule for the records that must be updated. In the XML payload sent with HTTP request for a batch operation, the filter alue is set in the rdf:alue in the oslc:namefilter/oslc:name property of the oslc_parameterinstance element in batch XML payload. 224 Jazz for Serice Management: Configuration Guide Draft

235 Table 73. Parameters used in the remapurl CLI (continued) Parameter Value Description -patternrule regular_expression This alue defines the regular expression string alue to be set in the rdf:alue in the oslc:namepattern/oslc:name property of the oslc_parameterinstance element in batch XML payload. If this regular expression string alue contains wildcard characters, you must enclose it with double quotation marks. The syntax for the regular expression string alue is the same as the syntax that the jaa.util.regex.pattern Jaa class supports. For more information, see jaa.util.regex.pattern -replacementvalue URL_replacement This alue defines the URL string with which the matched URLs in records are to be replaced. This alue is to be set in the rdf:alue in the oslc:namereplacement/oslc:name property of the oslc_parameterinstance element in the batch XML payload. [-keystore] file_name_path This alue defines the name of the keystore file that contains a certificate for a user that is mapped to a Registry Serices role. There can be multiple certificates. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystore property in the CLI.properties file. [-keystorepassword] password This alue defines the password for the certificate that is specified in the -keystore parameter. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystorepassword property in the CLI.properties file. [-truststore] file_name_path This alue defines the name of the truststore file that contains the certificate of the serer to which Registry Serices connects for processing this CLI. There can be multiple certificates to multiple serers. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststore property in the CLI.properties file. [-truststorepassword] password This alue defines the password for the certificate that is specified in the -truststore parameter. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststorepassword property in the CLI.properties file. [-keystoretype] type_name This alue defines the keystore type. The default alue for this optional parameter is the keystore.type specified in the jaa.security file of the JDK in use. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystoretype property in the CLI.properties file. Appendix. Jazz for Serice Management references 225

236 Table 73. Parameters used in the remapurl CLI (continued) Parameter Value Description [-truststoretype] type_name This alue defines the truststore type. The default alue for this optional parameter is the truststore.type specified in the jaa.security file of the JDK in use. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststoretype property in the CLI.properties file. [-properties] properties_file This alue defines that the.properties file must act as the source of the properties for remapping URLs. This parameter is optional. If you do not specify this parameter, the CLI.properties file is used as the source of properties. The properties that are required for running this CLI are appserer.host; appserer.port; appserer.user; and appserer.password, which are also proided for Registry Serices installation purposes. Registry Serices assumes the BASIC authentication mechanism for connecting to the serer if you do not define any of the required parameter alues -keystore, -keystorepassword, -truststore, and -truststorepassword. If you define all the required parameter alues, Registry Serices uses the CLIENT-CERT authentication mechanism for connecting to the serer. If you define the required parameter alues partially, then this CLI does not connect to Registry Serices and fails to proceed with your request. For parameter alues defined by path and file name, you must take an extra action according to the operating system in use: On Windows systems: if the path and the file name include a space character, enclose the entire path alue with double quotation marks. On Linux systems: if the path and the file name include a space character, escape this character with a back slash. Sample frs.bat remapurl -registrytype proider -patternrule.*\.mylab\.mylocale\.ibm\.com -replacementvalue frs1.mylab.mylocale.ibm.com C:\Program Files\IBM\Jaa\keycertificate.jks -keystorepassword truststore C:\Program Files\IBM\Jaa\trustcert.jks -truststorepassword properties C:\Registry Serices\etc\remap.properties./frs.sh remapurl -registrytype resource -patternrule.*\.mylab\.mylocale\.ibm\.com -replacementvalue frs1.mylab.mylocale.ibm.com /opt/ibm/jaa/keycertificate.jks -keystorepassword truststore /opt/ibm/jaa/trustcert.jks -truststorepassword keystoretype JKS Return codes The remapurl command prints a return code when it finishes running so you can hae details about the result achieed. Table 74 proides the return codes that you can get by the end of the remapurl run and their respectie descriptions Table 74. Return codes of the remapurl command run Return code Description 0 The remapurl command ran the operation successfully. 226 Jazz for Serice Management: Configuration Guide Draft

237 Table 74. Return codes of the remapurl command run (continued) Return Description code 1 The remapurl command failed to run because of a missing required parameter or an inalid parameter alue. 2 The remapurl command failed to run because of a properties file not found or inalid properties alues. 3 The remapurl command failed to run because of an internal error that is logged in the CLI log files. 4 The remapurl command failed to run because of a failure to connect to the automation batch URL by using the authentication details - HTTP status codes 401 (Unauthorized) or 403 (Forbidden). 5 The remapurl command failed to run because of the impossibility of accessing the automation batch URL - HTTP status code 404 (Not Found). 6 The remapurl command failed to run because of the impossibility of accessing the automation batch URL - HTTP status code 500 (Internal Serer Error). 7 The remapurl command failed to run because of the impossibility of accessing the automation batch URL - HTTP status code 400 (Bad Request). Recompute reconciled state command You can use the recomputereconciledstate command-line interface (CLI) to recompute the reconciliation state of the Registry Serices Resource Records. You might recompute the reconciliation state after an operation that resulted in the update of Resource Shape definitions or cleansing rules. You might run this process also as a result of the batch registration and unregistration operations, which you run with the reconciliation state disabled. For more information, see Operation mode configuration command. By default, this CLI reprocesses only the Resource Records that were reconciled before a Resource Shape or cleansing rule update. To aoid this behaior, you can use the parameter -all when you run this CLI. Fix Pack 2 You can also use the -stop parameter to stop the reconciliation process of the Resource Records at any time. Fix Pack 1 Registry Serices reconciles only the resources whose properties hae matching name and type. Command syntax The recomputereconciledstate CLI syntax aries according to the enironment in which it is run: Fix Pack 2 frs.bat recomputereconciledstate [-all -stop] [-keystore file_name_path] [-keystorepassword password] [-truststore file_name_path] [-truststorepassword password] [-keystoretype type_name] [-truststoretype type_name] [-properties properties_file] Fix Pack 2./frs.sh recomputereconciledstate [-all -stop] [-keystore file_name_path] [-keystorepassword password] [-truststore file_name_path] Appendix. Jazz for Serice Management references 227

238 [-truststorepassword password] [-keystoretype type_name] [-truststoretype type_name] [-properties properties_file] Parameters Table 75 lists the parameters that are used with the recomputereconciledstate CLI and proides their description. Table 75. Parameters used in the recomputereconciledstate CLI Parameter Value Description [-all] This parameter requires no alue. This alue defines that the recomputereconciledstate command must recompute the reconciled state of all the Resource Records in the Registry Serices database. Fix Pack 2 [-stop] This parameter requires no alue. This alue defines that the recomputereconciledstate command must stop the process to recompute the reconciled state of the Resource Records in the Registry Serices database. [-keystore] file_path This alue defines the name of the keystore file that contains a certificate for a user that is mapped to a Registry Serices role. There can be multiple certificates. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystore property in the CLI.properties file. [-keystorepassword] password This alue defines the password for the certificate that is specified in the -keystore parameter. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystorepassword property in the CLI.properties file. [-truststore] file_path This alue defines the name of the truststore file that contains the certificate of the serer to which Registry Sericesconnects for processing this CLI. There can be multiple certificates to multiple serers. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststore property in the CLI.properties file. [-truststorepassword] password This alue defines the password for the certificate that is specified in the -truststore parameter. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststorepassword property in the CLI.properties file. [-keystoretype] type_name This alue defines the keystore type. The default alue for this optional parameter is the keystore.type specified in the jaa.security file of the JDK in use. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystoretype property in the CLI.properties file. [-truststoretype] type_name This alue defines the truststore type. The default alue for this optional parameter is the truststore.type specified in the jaa.security file of the JDK in use. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststoretype property in the CLI.properties file. 228 Jazz for Serice Management: Configuration Guide Draft

239 Table 75. Parameters used in the recomputereconciledstate CLI (continued) Parameter Value Description [-properties] properties_file This alue defines that the.properties file must act as the source of the recomputing properties. This parameter is optional. If you do not specify this parameter, the CLI.properties file is used as the source of recomputing properties. For recomputing the reconciled state, you can specify batch.reconciliation.wait.time optional property. This property specifies the amount of time, in seconds, that the CLI waits to send a new request to the Registry Serices application. The default alue for this property is 60 seconds. Sample frs.bat recomputereconciledstate -all -properties C:/etc/recompute.properties frs.bat recomputereconciledstate -stop./frs.sh recomputereconciledstate -all Return codes The recomputereconciledstate command prints a return code when it finishes running so you can hae details about the result achieed. Table 76 proides the return codes that you can get by the end of the recomputereconciledstate run and their respectie descriptions Table 76. Return codes of the recomputereconciledstate command run Return code Description 0 The recomputereconciledstate command ran the operation successfully. 2 The recomputereconciledstate command failed to run because of a properties file not found or an inalid property. 3 The recomputereconciledstate command failed to run because the CLI was not able to communicate with the serer and start the operation. 4 The recomputereconciledstate command failed to run because the serer stopped during the operation. 5 The recomputereconciledstate command failed to run because of a recompute error. Resource Shape creation command Use the createresourceshapes command-line interface (CLI) to create custom Resource Shape definitions after the Registry Serices database installation. See OSLC Core Specification - Serice Proider for information about the format and syntax to create a Resource Shape XML file. Command syntax The createresourceshapes CLI syntax aries according to the enironment in which it is run: frs.bat createresourceshapes -file xml_file -dir xml_dir [-properties properties_file] Appendix. Jazz for Serice Management references 229

240 ./frs.sh createresourceshapes -file xml_file -dir xml_dir [-properties properties_file] Parameters Table 77 lists the parameters that are used with the createresourceshapes CLI and proides their description. Table 77. Parameters used in the createresourceshapes CLI Parameter Value Description -file xml_file This alue defines the XML file that contains the custom Resource Shape definitions to be imported to the Registry Serices database. -dir xml_dir This alue defines the directory that contains the set of custom Resource Shape definitions to be imported to the Registry Serices database. This CLI imports all the XML files in the specified directory. -properties properties_file This alue defines that the.properties file must act as the source of the property that is required for creating custom Resource Shape definitions. This parameter is optional. If it is not specified, the CLI.properties file is used as the source of those properties. The package.dir mandatory property becomes optional when you create a Resource Shape through the CLI. The Registry Serices database scripts location can be determined based on the location of frs.bat or frs.sh scripts. Howeer, if you specify a alue to this property in the.properties file, it takes precedence oer automatic determination. The new Resource Shape cannot conflict with any existing Resource Shape. This custom Resource Shape cannot describe the same rdf:type of any existing Resource Shape in the Registry Serices database. Sample frs.bat createresourceshapes -file shapes.xml./frs.sh createresourceshapes -dir Registry_Home/shapes/shapes.xml Return codes The createresourceshapes command-line interface (CLI) prints a return code at the end of their execution so that you can hae details about the result achieed. Table 78 proides the return codes that can be printed by the end of this CLI execution and their respectie descriptions: Table 78. Return codes of the createresourceshapes command run Return Description code 0 The custom Resource Shape definitions were successfully created. 1 The custom Resource Shape definitions creation failed to run because of a missing -file or -dir parameter. 2 The custom Resource Shape definitions creation failed to run because of a properties file not found. 230 Jazz for Serice Management: Configuration Guide Draft

241 Table 78. Return codes of the createresourceshapes command run (continued) Return code Description 3 The custom Resource Shape definitions creation failed to run because of an inalid -file or -dir parameter that is specified in the command line. 4 The custom Resource Shape definitions creation failed to run because of an unknown creation error. Fix Pack 2 98 Fix Pack 1 99 The custom Resource Shape definitions creation failed to run because Registry Serices is unable to determine the current operation mode. The custom Resource Shape definitions creation failed to run because the readonly operation mode is actie. Related information: OSLC Reconciliation Wiki Jazz for Serice Management Registry Serices Vocabulary Resource Shape update command Use the updateresourceshape command-line interface (CLI) to update a custom Resource Shape. You can add, remoe or modify attributes, properties or identification rules to it. With this CLI, you must not install a new ersion of Registry Serices eery time the update of Resource Shape definitions takes place. You can run the updateresourceshape CLI command to update custom Resource Shape created through the createresourceshapes CLI or oerride the default Resource Shape. The update of the Resource Shape definitions that the Registry Serices application defines takes place through fix packs only. The Registry Serices application alidates the XML file that you pass as the payload to update a created Resource Shape definition (through the -file parameter). This alidation aims at ensuring that this XML file contains: At least one resource type in the oslc:describes list. no matching oslc:describes property alues between different Resource Shape definitions. at least one oslc:property specified, which must conform to the OSLC specification. no property proiderrecord defined in the Resource Shape. no duplicate properties that contain the same oslc:propertydefinition alue. no properties that are defined in the Proider Record Resource Shape, which contains properties that are specific for Proider Records. at least one rr:identificationrule specified for the Resource Shape definition; this resource must refer to an existing property. no rr:identificationrule resource with the same rr:priority alue. The update operation does not take place if the payload fails to proide any of those alidation items. Appendix. Jazz for Serice Management references 231

242 When you update a custom Resource Shape, specially its oslc:describes fields or its identifying rules and properties, this update might result in the need of a new reconciliation process of all affected Resource Records. The steps that you must follow are: Change the Registry Serices operation mode to reconciliation. For example: frs.bat config -set operation.mode=reconciliation. See Operation mode configuration command. Update the Resource Shape through the updateresourceshape command. Run the Resource Record reconciliation process. Change the Registry Serices operation mode to normal: frs.bat config -set operation.mode=normal. Also, keep the Registry Serices operation mode set to reconciliation before you update the cleansing rules and until its reconciled state is fully recomputed. The updateresourceshape command checks the Resource Records that are affected by this update operation and calculates an approximate number. This approximate result does not affect any of the subsequent update operations or the reconciliation process itself. The command quickly checks how many Resource Records that the update operation affected, but does not check the actual reconciliation status. The Resource Shape update operation itself does not process the reconciliation, but Registry Serices warns you when the reconciliation process is required after the update. The Registry Serices application updates the dcterms:modified timestamp with the current database time eery time an existing custom Resource Shape definition gets to be updated. Command syntax The updateresourceshape CLI syntax aries according to the enironment in which it is run: frs.bat updateresourceshape [-url rs_url] -file file_name [-properties properties_file]./frs.sh updateresourceshape [-url rs_url] -file file_name [-properties properties_file] Parameters Table 79 on page 233 lists the parameters that are used with the updateresourceshape CLI and proides their description. 232 Jazz for Serice Management: Configuration Guide Draft

243 Table 79. Parameters used in the updateresourceshape CLI Parameter Value Description [-url] rs_url This alue defines the URL of the custom Resource Shape definition to be updated in the Registry Serices database. This URL must point to a registered Resource Shape and be the same as the URL that Registry Serices returns when you query for Resource Shape. This parameter alue becomes optional when you specify the dcterms:identifier attribute in the XML file. Howeer, the -url alue takes precedence oer the dcterms:identifier alue if both are specified. -file file_name This alue defines the XML file that contains the custom Resource Shape that matches exactly the definition to be updated in the Registry Serices database. This XML file must also contain the properties to be added to the Resource Shape definition. -properties properties_file This alue defines that the.properties file must act as the source of the property that defines the Resource Shape update and the properties that define the connection to the Registry Serices (ds.jdbc.drier, ds.jdbc.url, ds.jdbc.user and ds.jdbc.password). This parameter is optional. If it is not specified, the CLI.properties file is used as the source of those properties. The package.dir mandatory property becomes optional when you update Resource Shape definitions through the CLI. The Registry Serices database scripts location can be determined based on the location of frs.bat or frs.sh scripts. Howeer, if you specify a alue to this property in the.properties file, it takes precedence oer automatic determination. Fix Pack 1 If the root of the URL that you specify through the -url or -file CLI parameters is different from the root URL that Registry Serices uses, the later takes precedence. This conflict does not preent Registry Serices from updating the Resource Shape. Registry Serices uses the path portion of the URL that you specify in the request as a reference to the Resource Shape to be updated. Sample frs.bat updateresourceshape -url -file C:/new_rs.xml -properties C:/alternate_dir/etc/CLI.properties./frs.sh updateresourceshape -url -file /home/user/new_rs.xml Return codes The updateresourceshape command-line interface (CLI) prints a return code at the end of their execution so that you can hae details about the result achieed. Table 80 proides the return codes that can be printed by the end of this CLI execution and their respectie descriptions. Table 80. Return codes of the updateresourceshape command run Return Description code 0 Registry Serices successfully updated the custom Resource Shape. Appendix. Jazz for Serice Management references 233

244 Table 80. Return codes of the updateresourceshape command run (continued) Return code Description 1 Registry Serices failed to update the custom Resource Shape because of a missing -file and -url parameter. 2 Registry Serices failed to update the custom Resource Shape because of a properties file not found or any inalid property that is defined in this file. 3 Registry Serices failed to update the custom Resource Shape because of an inalid -file parameter that is specified in the command-line interface, or a missing Resource Shape within the specified URL. 4 Registry Serices failed to update the custom Resource Shape because of an inalid -file, or an inalid XML content within this file. 5 Registry Serices failed to update the custom Resource Shape because of an unknown error. Fix Pack 2 98 Fix Pack 1 99 The custom Resource Shape update failed to run because Registry Serices is unable to determine the current operation mode. Registry Serices failed to update the custom Resource Shape because the readonly operation mode is actie. Resource Shape deletion command You use the deleteresourceshapes command-line interface (CLI) to remoe custom Resource Shape definitions from the Registry Serices database. You use the deleteresourceshapes CLI command to remoe any custom Resource Shape you created through the createresourceshapes CLI command. If you delete a custom Resource Shape, but does not create a customized definition for the same Resource Shape, Registry Serices re-creates this Resource Shape from its internal copy. For example, if you delete a custom ComputerSystem definition, but does not create a new customized ComputerSystem again, Registry Serices re-creates the ComputerSystem Resource Shape from its current ersion. Command syntax The deleteresourceshapes CLI syntax aries according to the enironment in which it is run: frs.bat deleteresourceshapes -url rs_url -file file_name [-properties properties_file]./frs.sh deleteresourceshapes -url rs_url -file file_name [-properties properties_file Parameters Table 81 on page 235 lists the parameters that are used with the deleteresourceshapes CLI and proides their description. 234 Jazz for Serice Management: Configuration Guide Draft

245 Table 81. Parameters used in the deleteresourceshapes CLI Parameter Value Description -url rs_url This alue defines the URL of the custom Resource Shape to be remoed from the Registry Serices database. This parameter is optional if you proide the -file parameter. -file file_name This alue defines the text file that contains a list of custom Resource Shape URLs to be remoed from the Registry Serices database. There is a Resource Shape URL per line. This CLI deletes all Resource Shape referenced by the URLs contained in this file. This parameter is optional if the -url parameter is proided. -properties properties_file This alue defines that the properties file must act as the source of the property that defines the Resource Shape remoal. This parameter is optional. If it is not specified, the CLI.properties file is used as the source of those properties. The package.dir mandatory property becomes optional when you delete Resource Shape definitions through the CLI. The Registry Serices database scripts location can be determined based on the location of frs.bat or frs.sh scripts. Howeer, if you specify a alue to this property in the properties file, it takes precedence oer automatic determination. Fix Pack 1 If the root of the URL that you specify through the -url and -file CLI parameters is different from the root URL that Registry Serices uses, the later takes precedence. This conflict does not preent Registry Serices from deleting the Resource Shape. Registry Serices uses the path portion of the URL that you specify in the request as a reference to the Resource Shape to be deleted. Sample frs.bat deleteresourceshapes -file C:/rs/rs.txt -properties C:/alternate_dir/etc/container.properties./frs.sh deleteresourceshapes -url Return codes The deleteresourceshapes command-line interface (CLI) prints a return code at the end of their execution so that you can hae details about the result achieed. Table 82 proides the return codes that can be printed by the end of this CLI execution and their respectie descriptions. Table 82. Return codes of the deleteresourceshapes command run Return Description code 0 The custom Resource Shape definitions were successfully deleted. 1 The custom Resource Shape deletion failed to run because of a missing -file and --url parameter. 2 The custom Resource Shape deletion failed to run because of a properties file not found. 3 The custom Resource Shape deletion failed to run because of an inalid -file or --url parameter that is specified in the command line. 4 The custom Resource Shape deletion failed to run because of an unknown deletion error. Appendix. Jazz for Serice Management references 235

246 Table 82. Return codes of the deleteresourceshapes command run (continued) Return code 98 Fix Pack 2 Fix Pack 1 99 Description The custom Resource Shape deletion failed to run because Registry Serices is unable to determine the current operation mode. The custom Resource Shape deletion failed to run because the readonly operation mode is actie. Performance statistics command Use the stats command-line interface (CLI) to get the execution time of Registry Serices calls to analyze and improe the performance. Command syntax The stats CLI syntax aries according to the enironment in which it is run: frs.bat stats -minutes -hours -days period [-keystore file_name] [-keystorepassword password] [-truststore file_name] [-truststorepassword password] [-keystoretype type_name] [-truststoretype type_name] [-properties properties_file] [-erbose]./frs.sh stats -minutes -hours -days period [-keystore file_name] [-keystorepassword password] [-truststore file_name] [-truststorepassword password] [-keystoretype type_name] [-truststoretype type_name] [-properties properties_file] [-erbose] Parameters Table 83 lists the parameters that are used with the stats CLI and proides their description. Table 83. Parameters used in the stats CLI Parameter Value Description -minutes period This alue defines that the stats command must return the Registry Serices performance data from the period that is defined for this parameter, in minutes. The maximum alue that you can proide with the -minutes parameter is 59. -hours period This alue defines that the stats command must return the Registry Serices performance data from the period that is defined for this parameter, in hours. The maximum alue that you can proide with the -hours parameter is 23. -days period This alue defines that the stats command must return the Registry Serices performance data from the period that is defined for this parameter, in days. Valid alues that you can proide for the -days parameter ranges from 1 to 7. [-keystore] file_name This alue defines the name of the keystore file that contains a certificate for a user that is mapped to a Registry Serices role. There can be multiple certificates. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystore property in the CLI.properties file. 236 Jazz for Serice Management: Configuration Guide Draft

247 Table 83. Parameters used in the stats CLI (continued) Parameter Value Description [-keystorepassword] password This alue defines the password for the certificate that is specified in the -keystore parameter. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystorepassword property in the CLI.properties file. [-truststore] file_name This alue defines the name of the truststore file that contains the certificate of the serer to which Registry Serices connects for processing this CLI. There can be multiple certificates to multiple serers. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststore property in the CLI.properties file. [-truststorepassword] password This alue defines the password for the certificate that is specified in the -truststore parameter. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststorepassword property in the CLI.properties file. [-keystoretype] type_name This alue defines the keystore type. The default alue for this optional parameter is the keystore.type specified in the jaa.security file of the JDK in use. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystoretype property in the CLI.properties file. [-truststoretype] type_name This alue defines the truststore type. The default alue for this optional parameter is the truststore.type specified in the jaa.security file of the JDK in use. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststoretype property in the CLI.properties file. [-properties] properties_file This alue defines that the.properties file must act as the source of the properties that are required for taken the performance data. This -properties parameter is optional. If it is not specified, the CLI.properties file is used as the source of these properties. The properties that are required for taken the performance data are: appserer.host; appserer.port; appserer.user; and appserer.password, which are also proided for Registry Serices installation purposes. [-erbose] No alue is required This optional parameter requires no alue. The [-erbose] parameter defines how the performance report looks like. When you specify it in the CLI, the performance report displays not only the aggregated information, but also the elements that compose this information. If you do not define any of these required parameter alues (keystore, keystorepassword, truststore and truststorepassword), the Registry Serices assumes the BASIC authentication mechanism for connecting to the serer. Appendix. Jazz for Serice Management references 237

248 If you define all of these required parameter alues, Registry Serices uses the CLIENT-CERT authentication mechanism for connecting to the serer. If you define these required parameter alues partially, then this CLI does not connect to Registry Serices and fails to proceed with your request. This performance report example shows an output that you get if you specify the [-erbose] parameter in the CLI. The command line to get this output is frs.bat stats -hours 2 -erbose AGGREGATE ========== Records per hour: 100 Records per second: 0.03 Aerage duration for record create operation: 600 ms Min duration for create operation: 2000 ms Max duration for create operation: ms Records per hour: 178 Records per second: 0.05 Aerage duration for record delete operation: 224 ms Min duration for delete operation: 4000 ms Max duration for delete operation: ms Records per hour: 240 Records per second: 0.07 Aerage duration for record query operation: ms Min duration for query operation: ms Max duration for query operation: ms Records per hour: 68 Records per second: 0.02 Aerage duration for record reconciliation operation: 7058 ms Min duration for reconciliation operation: 4000 ms Max duration for reconciliation operation: ms Records per hour: 68 Records per second: 0.02 Aerage duration for record update operation: 1294 ms Min duration for update operation: ms Max duration for update operation: ms HOUR 1 ========== Records per hour: 50 Records per second: 0.01 Aerage duration for record create operation: 600 ms Min duration for create operation: 1000 ms Max duration for create operation: ms Records per hour: 89 Records per second: 0.02 Aerage duration for record delete operation: 224 ms Min duration for delete operation: 2000 ms Max duration for delete operation: 6000 ms Records per hour: 120 Records per second: 0.03 Aerage duration for record query operation: ms Min duration for query operation: ms Max duration for query operation: ms Records per hour: 34 Records per second: Jazz for Serice Management: Configuration Guide Draft

249 Aerage duration for record reconciliation operation: 7058 ms Min duration for reconciliation operation: 2000 ms Max duration for reconciliation operation: ms Records per hour: 34 Records per second: 0.01 Aerage duration for record update operation: 1294 ms Min duration for update operation: 8000 ms Max duration for update operation: ms HOUR 2 ========== Records per hour: 50 Records per second: 0.01 Aerage duration for record create operation: 600 ms Min duration for create operation: 1000 ms Max duration for create operation: ms Records per hour: 89 Records per second: 0.02 Aerage duration for record delete operation: 224 ms Min duration for delete operation: 2000 ms Max duration for delete operation: 6000 ms Records per hour: 120 Records per second: 0.03 Aerage duration for record query operation: ms Min duration for query operation: ms Max duration for query operation: ms Records per hour: 34 Records per second: 0.01 Aerage duration for record reconciliation operation: 7058 ms Min duration for reconciliation operation: 2000 ms Max duration for reconciliation operation: ms Records per hour: 34 Records per second: 0.01 Aerage duration for record update operation: 1294 ms Min duration for update operation: 8000 ms Max duration for update operation: ms If you do not specify the [-erbose] optional parameter in the stats command-line interface, the performance report does not show elements such as HOUR 1 and HOUR 2; the command shows the aggregate results only. This output shows the aggregated information for the last two hours of operation, according to your request. And you also get the detailed information about each of those two hours because you specified the -erbose parameter. There are fie different sets of performance report in this output. Each set shows the performance report of each operation that occurred during the specified amount of time, such as create, update, and delete. For example, if you run the command-line frs.bat stats -hours 2 -erbose now, within two hours you get this output, where the aggregate result shows: Records per hour: number The total amount of records that is processed within the specified period. Records per second: seconds The total amount of time the application took to process the amount of records, in seconds. Appendix. Jazz for Serice Management references 239

250 Aerage duration for operation_type operation: milliseconds The aerage amount of time the application took to process the specified operation, in milliseconds. Min duration for operation_type operation: milliseconds The minimum amount of time the application took to process the specified operation, in milliseconds. Max duration for operation_type operation: milliseconds The maximum amount of time the application took to process the specified operation, in milliseconds. Note: The performance results you get when you run the stats CLI do not persist after you restart the WebSphere Application Serer. Sample frs.bat stats -hours 12 -keystore C:\Program Files\IBM\Jaa\keycertificate.jks -keystorepassword truststore C:\Program Files\IBM\Jaa\trustcert.jks -truststorepassword properties C:\etc\performance.properties frs.bat stats -minutes 10 -erbose./frs.sh stats -days 3 -keystore /opt/ibm/jaa/keycertificate.jks -keystorepassword truststore /opt/ibm/jaa/trustcert.jks -truststorepassword erbose./frs.sh stats -hours 15 Return codes The performance statistics command-line interface (CLI) prints a return code at the end of its execution. With this return code, the user can hae details about the result achieed. Table 84 proides the return codes that can be printed by the end of this CLI execution and their respectie descriptions. Table 84. Return codes of the stats command run Return Description code 0 The stats command ran the operation successfully. 1 The stats command failed to run because of a missing required parameter or an inalid parameter alue. 2 The stats command failed to run because of a properties file not found or properties alues inalid 3 The stats command failed to run because of an internal error that is logged in the CLI log files. 4 The stats command failed to run because of a failure to connect to theregistry Serices application by using the authentication details. 5 The stats command failed to run because of the impossibility of accessing the Registry Serices resources - HTTP status code 404 (Not Found). 6 The stats command failed to run because of the impossibility of accessing the Registry Serices resources - HTTP status code 500 (Internal Serer Error). 7 The stats command failed to run because of an error in the serer response or a failure to parse the response. 240 Jazz for Serice Management: Configuration Guide Draft

251 Export cleansing rules command You can use the exportcleansingrules command-line interface (CLI) to list all cleansing rules of a specific type in the Registry Serices database. With this information, you can debug eentual problems. Use this CLI command to list default, custom, or effectie cleansing rules. The cleansing rules you list through the exportcleansingrules CLI command can be either saed in a file or printed on the screen. This command returns an output with the same format as the output of the cleansing rules file. This sample shows a possible output format: <Rules> <Rule property=" <Regex pattern="_" format=" " /> <Regex pattern=""" format="" /> <Regex pattern="^(?i:vmware)-" format="" /> <Trim /> <UpperCase /> </Rule> <Rule property=" <LowerCase /> </Rule> <Rule property=" <UpperCase /> </Rule> </Rules> Command syntax The exportcleansingrules CLI syntax aries according to the enironment in which it is run: frs.bat exportcleansingrules -type type [-file file_name] [-properties properties_file]./frs.sh exportcleansingrules -type type [-file file_name] [-properties properties_file] Parameters Table 85 lists the parameters that are used with the exportcleansingrules CLI and proides their description. Table 85. Parameters used in the exportcleansingrules CLI Parameter Value Description -type type This alue defines the type of cleansing rules to be listed. The aailable alues are: default, custom and effectie. [-file] file_name This alue defines the path to the output file. The -file parameter is optional. If you do not specify it, the Registry Serices uses the standard output. [-properties] properties_file This alue defines that the.properties file must act as the source of the exporting properties for the cleansing rules. This parameter is optional. If you do not specify this parameter, the CLI.properties file is used as the source of exporting properties of the cleansing rules. Appendix. Jazz for Serice Management references 241

252 Sample frs.bat exportcleansingrules -type custom -properties C:/etc/export.properties./frs.sh exportcleansingrules -type default Return codes The exportcleansingrules command prints a return code when it finishes running so you can hae details about the result achieed. Table 86 proides the return codes that you can get by the end of the exportcleansingrules run and their respectie descriptions. Table 86. Return codes of the exportcleansingrules command run Return Description code 0 The exportcleansingrules command ran the operation successfully. 1 The exportcleansingrules command failed to run because of a missing -type parameter. 2 The exportcleansingrules command failed to run because of a properties file not found or an inalid property. 3 The exportcleansingrules command failed to run because of an inalid -file parameter, because of an inexistent file or because the specified file is a directory. 4 The exportcleansingrules command failed to run because of an inalid -type parameter. Update cleansing rules command You can use the updatecleansingrules command-line interface (CLI) to replace the default by the custom cleansing rules in the Registry Serices application. This CLI command replaces all custom cleansing rules that exist in the Registry Serices database by the cleansing rules in the specified cleansing rules XML file. For the definition of cleansing rules, see Data cleansing mechanism. The updatecleansingrules command does not affect the default cleansing rules. Registry Serices always maintains these default cleansing rules in its database. Registry Serices preprocesses the cleansing rules XML file before it stores this file in the database. During this preious process, Registry Serices remoes white spaces and comments, and sets this XML file to UTF-8 encoding. Each preprocessed cleansing rule data cannot exceed the maximum size of 1 Mb. You can restore the default cleansing rules by specifying in the -file parameter an XML file with empty rules (<Rules></Rules>). When you use this command to update the custom cleansing rules, some Resource Records properties might end up with inalid alues. Therefore, run the recomputereconciledstate CLI command after you update the cleansing rules to run a batch reconciliation. Also, keep the Registry Serices 242 Jazz for Serice Management: Configuration Guide Draft

253 operation mode set to reconciliation before you update the cleansing rules and until its reconciled state is fully recomputed. This CLI command recomputes the reconciled state of the Resource Records, which might be required after an operation that resulted in the Resource Shape update. For more information, see Recompute reconciled state command. Command syntax The updatecleansingrules CLI syntax aries according to the enironment in which it is run: frs.bat updatecleansingrules -file file_name [-properties properties_file]./frs.sh updatecleansingrules -file file_name [-properties properties_file] Parameters Table 87 lists the parameters that are used with the updatecleansingrules CLI and proides their description. Table 87. Parameters used in the updatecleansingrules CLI Parameter Value Description -file file_name This alue defines the path to the file that contains an XML payload with the new cleansing rules. The updatecleansingrules command takes the cleansing rules from this file to update the existing ones. If this XML payload does not contain alid cleansing rules, the update operation fails. The cleansing rules length must not exceed the maximum limit that a string can hae in the Registry Serices database. For more information, see Data cleansing mechanism. [-properties] properties_file This alue defines that the.properties file must act as the source of the properties to update cleansing rules. This parameter is optional. If you do not specify this parameter, the CLI.properties file is used as the source of the properties to update cleansing rules. The properties that are required for running the updatecleansingrules command are: ds.jdbc.drier ds.jdbc.url ds.jdbc.user ds.jdbc.password Sample frs.bat updatecleansingrules -file C:/bin/ucr.xml -properties C:/etc/update.properties./frs.sh updatecleansingrules -file RegistrySerices/bin/updatecr.xml Appendix. Jazz for Serice Management references 243

254 Return codes The updatecleansingrules command prints a return code when it finishes running so you can hae details about the result achieed. Table 88 proides the return codes that you can get by the end of the updatecleansingrules run and their respectie descriptions. Table 88. Return codes of the updatecleansingrules command run Return code Description 0 The updatecleansingrules command ran the operation successfully. 1 The updatecleansingrules command failed to run because of a missing -file parameter or inalid cleansing rules in the XML file. 2 The updatecleansingrules command failed to run because of a properties file not found or an inalid property. 4 The updatecleansingrules command failed to run because of an inalid -file parameter. Fix Pack 2 98 Fix Pack 1 99 The updatecleansingrules command failed to run because Registry Serices is unable to determine the current operation mode. The updatecleansingrules command failed to run because the readonly operation mode is actie. Data cleansing mechanism: This mechanism is used by Registry Serices to normalize attribute alues to improe matching during reconciliation. The data registration mechanism generates and stores cleansed attribute alues in the Resource Records. It does not change the attribute alues in the Registration Records. Registry Serices also does data cleansing on parameters in queries to the Resource Record collection. Therefore, a client query for Resource Records can specify either cleansed or uncleansed alues. Howeer, a client query for Registration Records must specify the original alues. Registry Serices comes with a predefined set of cleansing rules for certain properties. Howeer, these rules can be customized and extended by using the command-line interface (CLI). These rules are applied to the associated property alues during reconciliation. Further details about the data cleansing rules include: The data cleansing rules are assigned to the namespace-qualified property names. The cleansing rules are stored in the Registry Serices database. The default cleansing rules are installed during the database installation. You can add, update, or delete any custom cleansing rules, but you cannot remoe any of the default rules from the database. You can also update the cleansing rules to restore the defaults through the command line. See Update database command. 244 Jazz for Serice Management: Configuration Guide Draft

255 If you create a custom cleansing rule for a property whose default cleansing rule exists, both rules are stored in the Registry Serices database. Howeer, the custom rule takes precedence oer the default. You can modify the custom cleansing rules at any time. You can restore the default cleansing rules by deleting any custom rules. You can define many cleansing rules for each property. The Registry Serices supports the usage of these cleansing rules: Regexp This rule matches the pattern in the input attribute. Then, it replaces all the matched strings with the specified format. Trim This rule remoes leading and trailing white spaces. UpperCase This rule conerts the string to an uppercase string. LowerCase This rule conerts the string to a lowercase string. MappingTable This rule replaces the input alues based on entries of a lookup table. It supports the matching of only literal alues and it works with plain text comparison. This rule does not enforce any specific limit of number of entries; only the general limit of a single cleansing rule size applies. The stanzas within each property rule are run in the same order as they are defined in the XML file. The cleansed alues, which are generated during the reconciliation process, are stored in the Resource Records. The cleansing process normalizes the alues so they can match een if they are represented in different forms. An HTTP GET request to the Resource Records returns the cleansed alues in the normalized format. And this request to the Registration Record returns the alues in their original format from the registered payload. The oslc.where parameter alues are cleansed before the query is run. The query mechanism uses cleansed alues when querying for Resource Records and original alues when querying for Registration Records. You can query for either the original or the cleansed alues. Either way, you always get the same result. Example The following example of custom data cleansing rules in XML format suitable for input to the cleansing rule customization CLI: <Rules> <Rule property=" <Regex pattern="^[^,]*,(.*)" format="$1" /> <UpperCase /> <Regex pattern="[^a-z0-9]" format="" /> <Regex pattern="vmware" format="" /> </Rule> <Rule property=" <LowerCase /> <Regex pattern="[^a-z0-9]" format="" /> <Regex pattern="([\da-f]{8})([\da-f]{4})([\da-f]{4})([\da-f]{4})([\da-f]{12})" format="$1-$2-$3-$4-$5" /> </Rule> Appendix. Jazz for Serice Management references 245

256 <Rule property=" <Regex pattern="^.*\x5b([^\x5b\x5d]*)].*" format="$1" /> <Regex pattern="^[^,]*,(.*)" format="$1" /> <UpperCase /> <Regex pattern="[^a-z0-9]" format="" /> </Rule> <Rule property=" <Regex pattern=""" format="" /> <Regex pattern="vmware *, *Inc\x2e?" format="vmware" /> <Trim /> <MappingTable> <Mapping alue="sun_microsystems" replacement="sun Microsystems" /> <Mapping alue="hp" replacement="hewlett-packard" /> </MappingTable> </Rule> <Rule property=" <Trim /> </Rule> <Rule property=" <UpperCase /> <Regex pattern="[^a-z0-9]" format="" /> </Rule> <Rule property=" <Trim /> <LowerCase /> </Rule> <Rule property=" <Trim /> <LowerCase /> </Rule> </Rules> Based on these cleansing rules, you can see: If the record is registered with a crt:model property alue of abcxyz123, the alue that is obtained after the rules defined for this property are applied is ABCXYZ123. You send the abcxyz123 alue, which the Registry Serices returns for HTTP GET requests to the Registration Records. The Registry Serices uses the ABCXYZ123 alue for reconciliation purposes and stores it in the Resource Record. You must use the abcxyz123 original alue for querying for Registration Records. You can use the abcxyz123 original alue for querying for Resource Records, which the Registry Serices cleans to the ABCXYZ123 alue. You can also use the ABCXYZ123 alue for querying for Resource Records to get the same result. The cleansing process does not change the alues; cleansed alues are presered. The serialnumber property alue is cleansed by: Remoing any characters that precede a comma, and by remoing the comma too. Upper-casing all letters. Remoing any non-alphanumeric characters. Remoing the VMWARE string, if it is displayed. Manage namespace prefixes command Fix Pack 2 You can use the managenamespaceprefixes command-line interface (CLI) to create, delete, and list new namespace prefix definitions. Any custom namespace prefix 246 Jazz for Serice Management: Configuration Guide Draft

257 definition that you create through the managenamespaceprefixes CLI cannot conflict with existing namespace prefix definitions. Command syntax The managenamespaceprefixes CLI syntax aries according to the enironment in which it is run: frs.bat managenamespaceprefixes -create -delete -list [-prefix namespace_prefix] [-url namespace_url] [-properties properties_file]./frs.sh managenamespaceprefixes -create -delete -list [-prefix namespace_prefix] [-url namespace_url] [-properties properties_file] Parameters Table 89 lists the parameters that are used with the managenamespaceprefixes CLI and proides their description. Table 89. Parameters used in the managenamespaceprefixes CLI. Parameter Value Description -create -delete -list This parameter requires no alue, but it requires -prefix and -url parameters This parameter requires no alue, but it requires -prefix and -url parameters This parameter requires no alue This alue defines that the managenamespaceprefixes command must create a new namespace prefix definition. This new namespace prefix definition is created according to the information that you specify on the -prefix and -url parameters. Registry Serices shows the new custom namespace prefix definitions on new prefixdefinition properties in the Proider Registry and Resource Registry SericeProider definitions. This alue defines that the managenamespaceprefixes command must delete a custom namespace prefix definition. This custom namespace prefix definition is deleted according to the information that you specify on the -prefix and -url parameters. If you specify only the -prefix parameter, the CLI command deletes the namespace prefix definition that matches the specified prefix alue. If you specify only -url, the command deletes the namespace prefix definition that matches the specified URL alue. If you specify both -prefix and -url parameters, the command deletes the namespace prefix definition that matches the two specified alues. Registry Serices remoes the prefixdefinition properties from the Proider Registry and Resource Registry SericeProider definitions for the custom namespaces that were deleted. This alue defines that the managenamespaceprefixes command must return a list of all custom and default namespace prefix definitions, including their URLs. Registry Serices returns a list of namespace prefixes and their URLs in the standard output. [-prefix] namespace_prefix This alue defines the prefix portion of the namespace prefix definition. [-url] namespace_url This alue defines the URL portion of the namespace prefix definition. Appendix. Jazz for Serice Management references 247

258 Table 89. Parameters used in the managenamespaceprefixes CLI (continued). Parameter Value Description [-properties] properties_file This alue defines that the properties file must act as the source of the custom namespace prefix definition properties. This parameter is optional. If you do not specify this parameter, the default REGISTRY_HOME\etc\CLI.properties file is used as the source of namespace prefix definition properties. Sample frs.bat managenamespaceprefixes -list./frs.sh managenamespaceprefixes -delete -prefix custom -url frs.bat managenamespaceprefixes -create -properties C:/etc/db.properties -prefix custom -url Return codes The managenamespaceprefixes command prints a return code when it finishes running so you can hae details about the result achieed. Table 90 proides the return codes that you can get by the end of the managenamespaceprefixes run and their respectie descriptions. Table 90. Return codes of the managenamespaceprefixes command. Return Description code 0 The managenamespaceprefixes command ran the operation successfully. 1 The managenamespaceprefixes command failed to run because of a missing parameter. 2 The managenamespaceprefixes command failed to run because of a properties file not found. 3 The managenamespaceprefixes command failed to run because of an inalid parameter that is specified in the command line. 4 The managenamespaceprefixes command failed to run because of a Registry Serices failure to add, delete, or list any custom namespace prefix definitions. 98 The managenamespaceprefixes command failed to run because Registry Serices is unable to determine the current operation mode. 99 The managenamespaceprefixes command failed to run because the readonly operation mode is actie. Health check command You can use the healthcheck command-line interface (CLI) to monitor the configuration state and the aailability health of Registry Serices. They are both reported in terms of good, warning or bad status. Command syntax The healthcheck CLI syntax aries according to the enironment in which it is run: frs.bat healthcheck -keystore file_name -keystorepassword password -truststore file_name -truststorepassword password [-keystoretype type_name] [-truststoretype type_name] [-properties properties_file] 248 Jazz for Serice Management: Configuration Guide Draft

259 ./frs.sh healthcheck -keystore file_name -keystorepassword password -truststore file_name -truststorepassword password [-keystoretype type_name] [-truststoretype type_name] [-properties properties_file] Parameters Table 91 lists the parameters that are used with the healthcheck CLI and proides their description. Table 91. Parameters used in the healthcheck CLI Parameter Value Description -keystore file_name This alue defines the name of the keystore file that contains a certificate for a user that is mapped to one of the roles in the Registry Serices application. There can be multiple certificates. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystore property in the CLI.properties file. -keystorepassword password This alue defines the password for the certificate that is specified in the -keystore parameter. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystorepassword property in the CLI.properties file. -truststore file_name This alue defines the name of the truststore file that contains the certificate of the serer to which Registry Serices connects for processing this CLI. There can be multiple certificates to multiple serers. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststore property in the CLI.properties file. -truststorepassword password This alue defines the password for the certificate that is specified in the -truststore parameter. This parameter is required for certificate authentication purposes. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststorepassword property in the CLI.properties file. [-keystoretype] type_name This alue defines the keystore type. The default alue for this optional parameter is the keystore.type specified in the jaa.security file of the JDK in use. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.keystoretype property in the CLI.properties file. [-truststoretype] type_name This alue defines the truststore type. The default alue for this optional parameter is the truststore.type specified in the jaa.security file of the JDK in use. If you do not specify this parameter, Registry Serices reads it from the jaax.net.ssl.truststoretype property in the CLI.properties file. -properties properties_file This alue defines that the.properties file must act as the source of the health check properties. This parameter is optional. If you do not specify this parameter, the CLI.properties file is used as the source of health check properties. The properties that are required for running a health check are: appserer.host; appserer.port; appserer.user; and appserer.password, which are also proided for Registry Serices installation purposes. If you do not define any of the required parameter alues (keystore, keystorepassword, truststore and truststorepassword), the Registry Serices assumes the BASIC authentication mechanism for connecting to the serer. Appendix. Jazz for Serice Management references 249

260 If you define all the required parameter alues, Registry Serices uses the CLIENT-CERT authentication mechanism for connecting to the serer. If you define the required parameter alues partially, then this CLI does not connect to Registry Serices and fails to proceed with your request. Sample frs.bat healthcheck -keystore C:\Program Files\IBM\Jaa\keycertificate.jks -keystorepassword truststore C:\Program Files\IBM\Jaa\trustcert.jks -truststorepassword properties C:\Registry Serices\etc\health.properties./frs.sh healthcheck -keystore /opt/ibm/jaa/keycertificate.jks -keystorepassword truststore /opt/ibm/jaa/trustcert.jks -truststorepassword keystoretype JKS Return codes The healthcheck command prints a return code when it finishes running so you can hae details about the result achieed. Table 92 proides the return codes that you can get by the end of the healthcheck run and their respectie descriptions. Table 92. Return codes of the healthcheck command run Return code Description 0 The healthcheck command ran the operation successfully. 1 The healthcheck command failed to run because of a missing required parameter or an inalid parameter alue. 2 The healthcheck command failed to run because of a properties file not found or inalid properties alues. 3 The healthcheck command failed to run because of an internal error that is logged in the CLI log files. 4 The healthcheck command failed to run because of a failure to connect to the Registry Serices application by using the authentication details. 5 The healthcheck command failed to run because of the impossibility of accessing the Registry Serices resources - HTTP status code 404 (Not Found). 6 The healthcheck command failed to run because of the impossibility of accessing the Registry Serices resources - HTTP status code 500 (Internal Serer Error). Show ersion command You can use the showversion command-line interface (CLI) to get the ersion of any.jar files that are installed in the Registry Serices application. You can also use this command to get the ersion of the current installed runtime application. By default, this command returns the ersion of the.jar files that are installed in the JazzSM_HOME/lib/frs folder. Command syntax The showversion CLI syntax aries according to the enironment in which it is run: frs.bat showversion [-jarslocation jars_path] [-ear] [-properties properties_file]./frs.sh showversion [-jarslocation jars_path] [-ear] [-properties properties_file] 250 Jazz for Serice Management: Configuration Guide Draft

261 Parameters Table 93 lists the parameters that are used with the showversion CLI and proides their description. Table 93. Parameters used in the showversion CLI Parameter Value Description [-jarslocation] jars_path The -jarslocation parameter defines that the showversion command returns the ersion of all JAR files that are in the directory you specified. [-ear] This parameter requires no alue The -ear parameter defines that the showversion command must return the ersion of the Registry Serices application that is installed. [-properties] properties_file This alue defines that the.properties file must act as the source of Registry Serices properties. This parameter is optional. If you do not specify this parameter, this command uses the default REGISTRY_HOME\etc\CLI.properties file as the source of properties. A mandatory property becomes optional when you configure Registry Serices through the CLI. This property is package.dir. Registry Serices can determine the location of the file this property specifies based on the location of frs.bat or frs.sh scripts. Howeer, if you specify this property in the.properties file, it takes precedence oer automatic determination. Sample frs.bat showversion -jarslocation C:/WebSphere/runtimes/com.ibm.ws.admin.client.jar./frs.sh showversion -ear Return codes The showversion command prints a return code when it finishes running so you can hae details of the result achieed. Table 94 proides the return codes that you can get by the end of the showversion command run and their respectie descriptions. Table 94. Return codes of showversion command run Return Description code 0 The showversion command ran the operation successfully. 1 The showversion command failed to run because of an error to read the JAR file. 2 The showversion command failed to run because of an inalid directory that is specified in the command line. 3 The showversion command failed to run because of an error to retriee the EAR file ersion from IBM WebSphere Application Serer. 4 The showversion command failed to run because of an incorrect parameter that is specified in the command line. 5 The showversion command failed to run because there was not a JAR file that is specified in the -jarslocation parameter. Appendix. Jazz for Serice Management references 251

262 Security Serices commands Security Serices uses wsadmin scripting tool and its own command-line interfaces to manage Security Serices configurations and debug problems with basic authentication and single sign-on between applications. Security Serices commands (wsadmin scripting) Security Serices proides a set of WebSphere extensions to use with the AdminTask object. You run these commands with the wsadmin scripting tool to configure the Authentication Serice. createesssigner: Use the createesssigner command to configure the Authentication Serice to use keys from the default keystore for response signing. The AdminTask object runs this command with the wsadmin tool. Authentication Serice signs response data to proide increased security. By default, the Authentication Serice is configured to sign response data by using a key and associated certificate from a DefaultKeyStore.JKS keystore file. This default keystore is not confidential, so you must generate a key that is stored in a secure keystore file. Syntax $AdminTask createesssigner Operations None. Output None. Exceptions The command throws exceptions as follows: If a system error occurs If the Authentication Serice is not configured Example $AdminTask createesssigner exportesssignercert: Use the exportesssignercert command to export the certificates for response signing from the Authentication Serice to the specified keystore. The AdminTask object runs this command with the wsadmin tool. Syntax $AdminTask exportesssignercert {-pathname path_to_exported_keystore_file -password key_password -certalias cert_alias } 252 Jazz for Serice Management: Configuration Guide Draft

263 Operations -pathname path_to_keystore_file Sets the path and file name of the keystore file into which the certificates for response signing are exported, as specified by path_to_keystore_file. This operation is required. -password keystore_password Sets the password to protect the keystore file, as specified by keystore_password. This operation is required. -certalias signer_key_alias Sets the alias of the certificate in the specified keystore. This operation is required. Output None. Exceptions The command throws exceptions as follows: If a system error occurs If the Authentication Serice is not configured If the specified keystore file cannot be located Example $AdminTask exportesssignercert {-pathname path_to_exported_keystore_file -password key_password -certalias cert_alias } importesssigner: Use the importesssigner command to configure the Authentication Serice to use keys from the specified keystore for response signing. The AdminTask object runs this command with the wsadmin tool. Syntax $AdminTask importesssigner {-pathname path_to_exported_keystore_file -password key_password -keyalias signer_key_alias [-keypassword signer_key_password]} Operations -pathname path_to_exported_keystore_file Sets the path and file name of the keystore file, as specified by path_to_exported_keystore_file. This operation is required. -password keystore_password Sets the password to protect the keystore file, as specified by keystore_password. This operation is required. -keyalias signer_key_alias Sets the alias of the signer key in the specified keystore file. This operation is required. Appendix. Jazz for Serice Management references 253

264 -keypassword signer_key_password Sets the password to access the signer key in the specified keystore file. This operation is optional. Output None. Exceptions The command throws exceptions as follows: If a system error occurs If the Authentication Serice is not configured If a required operation is missing If the specified keystore file cannot be located Example $AdminTask importesssigner {-pathname path_to_exported_keystore_file -password key_password -keyalias signer_key_alias [-keypassword signer_key_password]} isessconfigured: Use the isessconfigured command to check whether the Authentication Serice was configured. The AdminTask object runs this command with the wsadmin tool. Syntax $AdminTask isessconfigured Operations None. Output The command returns one of the following alid alues: true The Authentication Serice is configured. You can change the configuration by first remoing the current configuration. false The Authentication Serice is not configured. You can now configure the Authentication Serice. Exceptions The command throws an exception if a system error occurs. Example $AdminTask isessconfigured 254 Jazz for Serice Management: Configuration Guide Draft

265 Figure 1. Output from the isessconfigured command isessconfiguredltpakeys: Use the isessconfiguredltpakeys command to check whether the Lightweight Third Party Authentication (LTPA) keys was configured for the Authentication Serice. The AdminTask object runs this command with the wsadmin tool. Syntax $AdminTask isessconfiguredltpakeys Operations None. Output The command returns one of the following alid alues: true The LTPA keys hae been configured for the Authentication Serice. You can change the LTPA key configuration; howeer, oerriding existing LTPA keys might inalidate preiously issued LTPA tokens. false The LTPA keys hae not been configured for Authentication Serice. You can configure the LTPA keys. Exceptions The command throws exceptions as follows: If a system error occurs If the Authentication Serice is not configured Example $AdminTask isessconfiguredltpakeys Appendix. Jazz for Serice Management references 255

266 Figure 2. Output from the isessconfiguredltpakeys command Table 95. LTPA configuration properties modifyessltpaconfiguration: Use the modifyessltpaconfiguration command to modify the Lightweight Third Party Authentication (LTPA) configuration of the Authentication Serice. The AdminTask object runs this command with the wsadmin tool. Syntax $AdminTask modifyessltpaconfiguration {[-ersion token_ersion] [-expiration token_expiration] [-usefips true false]} Operations -ersion token_ersion Sets the ersion of the new LTPA tokens that are issued, as specified by token_ersion. -expiration token_expiration Sets the time after which the newly created LTPA tokens expire, as specified by token_expiration. -usefips true false Sets whether to use the Federal Information Processing Standard (FIPS) approed cryptographic algorithm. Table 95 summarizes the property names and alid alues for those properties. Property Data type Default Configuration type Description Required ltpa.self.expiration long 120 self Time in seconds after which the LTPA tokens expire. Yes ltpa.self.usefips boolean false self Boolean flag to determine whether an FIPS-approed cryptographic algorithm is used. ltpa.self.ersion list or string if the list does not exist 2 self Version of the LTPA token that is issued. No Yes 256 Jazz for Serice Management: Configuration Guide Draft

267 Table 95. LTPA configuration properties (continued) Property Data type Default Configuration type Description Required ltpa.partner.usefips boolean false self Boolean flag to determine whether an FIPS-approed cryptographic algorithm is used. No Output None. Exceptions The command throws exceptions as follows: If a system error occurs If the Authentication Serice is not configured Example $AdminTask modifyessltpaconfiguration {[-ersion token_ersion] [-expiration token_expiration] [-usefips true false]} showessltpaconfiguration: Use the showessltpaconfiguration command to return the default Lightweight Third Party Authentication (LTPA) configuration details for the Authentication Serice as a properties object. The AdminTask object runs this command with the wsadmin tool. Syntax $AdminTask showessltpaconfiguration Operations None. Output The command returns a properties object that contains the LTPA configuration details as summarized by Table 96. Table 96. LTPA configuration properties Property Data type Default Description ltpa.self.arekeysset boolean true Boolean flag to determine whether the LTPA keys are configured for the Authentication Serice ltpa.self.expiration long 120 Time in seconds after which the LTPA tokens expire. Appendix. Jazz for Serice Management references 257

268 Table 96. LTPA configuration properties (continued) Property Data type Default Description ltpa.self.password archar alphanumeric characters ltpa.self.priatekey archar alphanumeric characters ltpa.self.publickey archar alphanumeric characters ltpa.self.sharedkey archar alphanumeric characters Password to protect the keys created by the Authentication Serice. The password must be same one used when the keys were created by the Authentication Serice. Priate decryption key of the Authentication Serice. Public encryption key of the Authentication Serice. Combined key of the Authentication Serice. ltpa.self.usefips boolean false Boolean flag to determine whether an FIPS-approed cryptographic algorithm is used. ltpa.self.ersion list or string if the list does not exist 2 Version of the LTPA token that is issued. ltpa.partner.arekeysset boolean true Boolean flag to determine whether the LTPA keys are configured for the partner. ltpa.partner.password archar alphanumeric characters ltpa.partner.publickey archar alphanumeric characters ltpa.partner.sharedkey archar alphanumeric characters Password to protect the keys created by the partner. The password must be same one used when the keys were created by the partner. Public encryption key of the Authentication Serice. Combined key of the partner. ltpa.partner.usefips boolean false Boolean flag to determine whether an FIPS-approed cryptographic algorithm is used. Exceptions The command throws exceptions as follows: If a system error occurs If the Authentication Serice is not configured Example $AdminTask showessltpaconfiguration 258 Jazz for Serice Management: Configuration Guide Draft

269 Figure 3. Output from the showessltpaconfiguration command Security Serices authnsccli CLI commands Fix Pack 1 Security Serices proides a command-line interface to run natie commands. The Windows command prompt does not hae support for AR, HE, and TH character sets. When you run commands from the Security Serices command-line interface in the command prompt, CLI output might be corrupted in these locales because of this limitation. You can display CLI messages in English or another supported language by setting the IBM_JAVA_OPTIONS enironment ariable before your run the authnsccli CLI. For example, to set the language to German: set IBM_JAVA_OPTIONS=-Duser.language=de Run Security Serices CLI help authnsccli.bat -help securityconfighealthstatus command: Fix Pack 1 Use the securityconfighealthstatus command to display the health status of the Security Serices configuration state. Syntax authnsccli.sh bat securityconfighealthstatus -profilelocation path_to_profile -profiletype appserer [-help] Parameters -profilelocation path_to_profile Specify the path to the WebSphere application serer profile. -profiletype appserer Specify the type of WebSphere profile. Example AIX Linux System z./authnsccli.sh securityconfighealthstatus -profilelocation /opt/ibm/jazzsm/profile -profiletype appserer Windows authnsccli.bat securityconfighealthstatus -profilelocation "C:\Program Files\IBM\JazzSM\profile" -profiletype appserer Appendix. Jazz for Serice Management references 259