7021570: How to Reset Verastream Management Server

Under certain circumstances, such as lost or forgotten administrative credentials, you may want to reset the configuration of the Verastream Management Server component, rather than uninstall and reinstall the entire Verastream Host Integrator (VHI) product. This technical note describes how to reset the management server.

What is Management Server?

Verastream Management Server is a component of Verastream Host Integrator that provides support for the following features:

The management server does not store other session server configuration including deployed models, pools, model variable lists, etc.

Why Reset?

Resetting the management server may be appropriate under one of the following circumstances:

  • The management server “admin” administrative password has been forgotten. This password is set during installation, or changed in Administrative Console.
  • The management server does not remain started due to corrupted configuration, which is identified by an error in the Attachmate/Verastream/ManagementServer/logs/server.log file, such as the following:
com.attachmate.integration.container.impl.ContainerMain - Error starting Verastream Server Container

org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'permissionMgrDatastoreMgr' defined in URL [file:/C:/Program%20Files/Attachmate/Verastream/ManagementServer/services/authorization/META-INF/service-ctx.xml]: ...

or:

com.attachmate.container.impl.ContainerMain - Error starting Verastream Server Container org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'permissionMgrMBean'
WARN [replication]: Several login attempts have failed to server at address <host name>/<IP address>. This usually indicates that this management server erroneously thinks it is part of a remote cluster and needs to be reset or the remote management server needs to be removed from this cluster.
  • After upgrading VHI to version 7.6 on the IBM AIX platform, the session server does not remain running and creates core dump files (caused by management cluster certificates originally generated by version 7.1.x).

Impacts of Reset

IMPORTANT! Resetting the management server will delete the following configuration in Administrative Console:

  • Authentication directory servers (in Management > Directories)
  • Authorization users and groups (in Management > Authorization)
  • Session server load distribution domains
  • Session pool start/stop schedules (in pool properties)
  • Session server registration with the management server
  • Host Emulator server
  • Administrative password (For the username admin, the password is reset to secret for VHI 7.7 and earlier, or secretpassword for VHI 7.7 SP1 and later.)

If you are using any of the above features, you will need to re-configure them after reset as directed in the procedure below. Note: All other session server configuration remains intact, including deployed models, pools, model variable lists, etc.

Related:

7022210: Installing the Reflection for the Web or Reflection Security Gateway Portlet on a WebSphere Portal Server

Before You Begin

Before installing the Reflection for the Web or Reflection Security Gateway (hereinafter called Reflection) portlet, you must have the following installed and configured.

  • WebSphere Portal Server 5.x or higher
  • Reflection must be running on an application server with sessions configured for your users. The following technical notes provide examples of installing Reflection on an application server: Technical Note 1779 and Technical Note 2332.

Obtaining the RWebPA.war File

Prior to installing the portlet, you must obtain the RWebPA.war file, which you will use to install the Reflection portlet.

  • If you have WebSphere Application Server installed, the RWebPA.war file is located in %WASHOME%installedAppsRWebWASAS6Node01Cellrweb_war.earrweb.warWEB-INFmisc.
  • If you do not have WebSphere Application Server installed, you can extract the RWebPA.war file from the rweb.war file located in the nonautomated directory of the downloaded product files (or on the Reflection CD). Use an archiving utility, such as WinZip, to extract the .war file.

Installing Reflection Portlet on the WebSphere Portal Server

With Reflection installed and configured on your application server, you are ready to install the Reflection portlet to the WebSphere Portal Server.

  1. Copy the RWebPA.war file to a temporary directory on the WebSphere Portal Server.
  2. Open a browser and log in to the portal with an account that has administrative rights.
  3. Click the Administration option in the upper-right corner of the screen.
  4. Click Portlet Management on the left pane to open the Manage Web Modules page.
  5. Click Install and enter the path, including the filename RWebPA.war, or browse to the RWebPA.war file (for example, C:tempRWebPA.war or /u/local/RWebPA.war).
  6. Click Next, and then click Finish.
  7. Under Portlet Management, click Portlets. From the list of portlets, select “RWeb portlet.”

There are multiple pages listing the portlets. You can use the Search tool to locate the RWeb portlet; select “Title starts with” or “Title contains” from the Searchby drop-down list, and enter rweb in the Search field. If RWeb portlet is not listed, you may have to logout and log back into the portal server for the portlet to be listed.

  1. On the right side of the Portlet row, click the Configure icon to setup the portlet.
2348_0.gif
  1. Two parameters are listed for the RWeb portlet. Make a note of the parameters and values listed; they will be used later.
  2. To provide the correct URL for the portlet, you must delete the parameter RWebURL, and then add it back:
    1. Delete RWebURL.
    2. Under New parameter, enter RWebURL. (This parameter is case sensitive).
  3. Under New value, enter the URL exactly as it was displayed in the example (for example, http://myserver:9080/rweb/LoginPage.do?appletOnly=true), but update the localhost name and port with the DNS name (or IP address) and port of the Reflection for the Web server.

To launch a session automatically when the user opens the portal page, enter that specific session’s URL (which can be copied from the Session Manager on the Administrative WebStation) as the RWebURL value.

  1. Click Add, and then click OK.

You can now add the Reflection portlet to any of the WebSphere portal pages.

Configuring the Shared Secret between the Portlet and the Reflection Server

The RWebPA.properties file contains the shared secret that the portlet uses to authenticate to the Reflection server. The shared secret needs to match what is configured on the Reflection server.

  1. Create a text file named RWebPA.properties at the location defined in the value of AC.RWebSSOSharedKeyPropsFile; see step 9 in Installing Reflection Portlet on the WebSphere Portal Server.
  2. In the RWebPA.properties file add the following line:
AC.RWebSSOSharedKey=sharedsecret

Replace sharedsecret (case sensitive) with the value you want to use to authenticate the portlet to the Reflection for the Web server.

  1. Save the file.
  2. Launch the Reflection Administrative WebStation.
  3. Under Tools, click Access Control Setup > Configure.
  4. Under “Choose authentication method,” click Portal, and then click Next.
  5. Enter the shared secret (case sensitive) that was added to the RwebPA.properties in step 2, and then click Next.
  6. Select the authorization method that best meets your needs and click Next.
  7. Click Save Settings.
  8. Click Access Mapper and assign the sessions you would like users to see.

Configuring the WebSphere Application Server

If you run Reflection on a WebSphere Application Server (WAS), then you must enable “URL rewriting” on the WAS server.

If you run Reflection on another application server (not WAS), skip this section and proceed to Adding the Portlet to the WebSphere Portal (An Example).

Note: At this time, you can enable “URL rewriting” on the WAS at the server level only, not at the application level.

  1. Open and log in to the WAS Administration Console.
  2. Click Servers > Application servers.
  3. Click the server on which Reflection is installed.
  4. Click Session management.
  5. Select the “URL rewriting” check box to enable it.
  6. Click OK.
  7. Click Save to save the change to the master configuration.
  8. Stop and restart the WAS server.

Adding the Portlet to the WebSphere Portal (An Example)

The following steps describe one way to add the Reflection portlet to a WebSphere portal page.

  1. Open and log in to the portal with an account that has administrative rights.
  2. Click the Administration option in the upper-right corner of the screen.
  3. Under the left pane, click Portal User Interface > Manage Pages.
  4. Click My Portal under the Title column.
  5. Click the Edit Page Layout icon on the right of the Welcome page row.
2348_1.gif
  1. In one of the three columns, click Add portlets.
  2. Scan the list of portlets and select the “RWeb portlet” check box.
  3. Click OK. The portlet should be added to the configuration of the Welcome page.
  4. Click Done.

Test the Portlet

Follow these steps to ensure that the portlet works.

  1. Log in to the WebSphere Portal server.
  2. Select the web page to which the portlet was added.
  3. Verify that Reflection sessions are listed in the portlet.

Related:

7022220: Installing Reflection for the Web or Reflection Security Gateway with WebSphere Application Server

Before You Begin

Before installing Reflection for the Web or Reflection Security Gateway (hereinafter referred to as Reflection), you must have all of the following installed and configured on your host.

  • WebSphere Application Server 5.0.2 or higher.
  • Java Developer Kit 1.5 or higher.
  • Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files. For details, see Applying the JCE Unlimited Strength Jurisdiction Policy Files.
  • The most recent WebSphere cumulative and group program temporary fixes (PTFs) must be applied.
  • Reflection requires 220 MB of free disk space in the hosts /tmp file during installation.
  • If you want to use security (HTTPS, SSL) with the WebSphere Application Server (WAS), refer to your IBM documentation to properly configure the WAS.

Installing Reflection for the Web

After the WebSphere Application Server has been properly installed and tested, follow the steps below to install Reflection.

Prepare the rweb.war File

Follow these steps to prepare the rweb.war file:

  1. Copy the rweb.war file located with the downloaded product files to a temporary folder on your PC. The file location depends on your Reflection product:

Reflection for the Web 2014 or 2011 or Reflection Security Gateway 2014: /install_manual/components/rweb.war

Reflection for the Web 2008: /nonautomated/rweb.war

  1. During download, the rweb.war file may be named rweb.war.zip. If so, rename rweb.war.zip to rweb.war.

Note: When renaming the file, you may receive an error stating that the file may become unstable. Click Yes to proceed.

Update the WebSphere Server Settings

Follow the steps below to update the WebSphere Server settings:

  1. Open the WebSphere Administration Console. By default, this is accessed from http://<myserver>:9060/admin or http://<myserver>: 9060/ibm/console.
  2. On the left-navigation bar, expand Applications, and then click Install New Application.
  3. In the main window, select the “Local file system” radio button and enter the path to the rweb.war file. For example:

C:Temprweb.war –or– /u/local/rweb.war

  1. Select the “Show me all installation options and parameters” radio button.
  2. In the Context root entry field, enter /rweb, and then click Next.
  3. Select the “Generate Default Bindings” check box, leave all other values at default, and then click Next.
  4. Click Next through the Install New Application dialog box, accepting defaults.
  5. Select the rweb.war check box, make sure the Virtual Host is set to default_host, and then click Next.
  6. Print the Summary page for your records, and then click Finish.

The new rweb.war application is installed and the Administration Console screen opens. If you expand the Applications menu and select Enterprise Applications, the application state for rweb should be Stopped.

Click Save to update the master configuration.

Update the web.xml File

There are two copies of the web.xml file, located in the following directories:

/WAS_install_root/installedApps/<cellname>/rweb.ear/rweb.war/WEB-INF/web.xml

– and –

/WAS_install_root/config/cells/<cellname>/applications/rweb.ear/deployments/rweb/rweb.war/WEB-INF/web.xml

Note: If this is a WebSphere Application Server Network Deployment, there is an additional web.xml that must be updated:

/IBM/WebSphere/AppServer/profiles/Dmgr01/config/cells/<dellname>/applications/rweb_war.ear/deployments/rweb_war/rweb.war/web.xml

In both (or all three) files, locate the <param-name>ReflectionData</param-name> section and modify the file to include the data in red below, entering your path to ReflectionData (for example, C:ReflectionData or /u/local/ReflectionData), and substituting your own sslport value for 443. Note: If the ReflectionData directory does not already exist, you must manually create it.

<context-param>

<param-name>ReflectionData</param-name>

<param-value><PathTo>ReflectionData</param-value>

</context-param>

<context-param>

<param-name>sslport</param-name>

Reflection stores configuration information in the ReflectionData directory. If this is a UNIX installation, ensure that rights are set so that Reflection can write to the ReflectionData directory.

Note: In Reflection, the sslport parameter is located in the PropertyDS.xml file, which is located in the ReflectionData folder. If you want to use a port other than default port 443; you must edit PropertyDS.xml after Reflection for the Web is started in WebSphere.

Once you have updated and saved both (or all three) of the web.xml files, return to the Administrative Console window and follow the steps below.

  1. Expand the Applications menu item, and then click Enterprise Applications.
  2. In the Enterprise Applications dialog, select the rweb check box, and then click Start. The application status will change to a started, indicated by a green arrow in the Status field.
  3. Update the sslport parameter in the PropertyDS.xml, if you need to. Once updated, restart the Application Server using the WebSphere Administrative Console, performing steps 1 and 2 above.

Reflection is now installed. To access Reflection, open a browser and enter the URL, WAS port, and context root to your server.

Syntax: http://myserver:default_port/context_root

For example: http://rweb.atm.com:9080/rweb

Applying the JCE Unlimited Strength Jurisdiction Policy Files

Reflection Security Gateway 2014 R2 and Reflection for the Web 2014 R2 require the Java Cryptography Extension (JCE) Unlimited Strength Policy Files. “Unlimited strength” policy files contain no restrictions on cryptographic strengths, in contrast to the “strong” but limited cryptography policy files bundled in a JRE.

To apply the policy files:

  1. Download the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files from Oracle or IBM. Be sure to download the correct policy file updates for your version of Java:
  1. Uncompress and extract the downloaded file. The download includes a Readme.txt and two .jar files with the same names as the existing policy files.
  2. Locate the two existing policy files local_policy.jar and US_export_policy.jar in the following directory:

– UNIX:<java-home>/lib/security

– Windows:C:Program FilesJavajre<version>libsecurity

  1. Replace the existing policy files with the unlimited strength policy files you extracted.

Related:

7021550: Comparing Web Services in Verastream Host Integrator 6.x vs. 7.x

About Web Services

Web services provide a standard means of communication that enable data to be exchanged between applications over a network. The web services protocol (SOAP) consists of XML data transmitted over HTTP. Verastream Host Integrator provides web service support, which enables other applications (web service clients) to interact with host applications.

Each web service provides a Web Services Description Language (WSDL) document, which defines the operations offered and can be used by third-party tools to automatically generate client-side code.

What’s New in Version 7.x Web Services

The following table summarizes how web services functionality in version 7.1 and 7.0 compare with earlier versions.

Web Services Functionality
Version 7.1.1142 (7.1+SP1)
Versions 7.0 through 7.1.221
Earlier Versions
Component(s) providing web services
Session server (embedded SOAP stack; does not require or use Tomcat or IIS)
Projects created in Web Builder are deployed to Tomcat/Axis “VHI Web Server” (for Java) or Microsoft IIS (for .NET)
Enablement process
Automatic when model package is deployed
Manual build and deployment, which must be repeated when model is changed
Configuration
Administrative Console (See Configuring Version 7.1.1142 below)

Edit service-ctx.xml file (See Configuring Version 7.0 through 7.1.221 below)

Project properties in Web Builder
Stateful web services (multiple client calls using the same host session)
Automatically provided with WS-Addressing and WS-Resource if your SOAP client also supports these standards. (See Stateful Web Services in Version 7.x below.)

Requires manual modification of Web Builder-generated .asmx.cs file to use suspendSession and resumeSession methods, return a session key value on connect, and use this token as an input value for each model procedure method.
SSL (HTTPS) encryption security
Supported (See Encryption in Version 7.x below)

Not supported
Access control security
Credentials can be transmitted in SOAP headers or HTTP basic authentication. (See Authentication and Authorization in Version 7.x below.)

Credentials must be passed in the data payload as input values for the Connect method.
Procedures and model features
All procedures are automatically available. To enable Execute SQL Statement or the ProcessString event handler, enable options in Administrative Console > Server, Model, or Pool Properties > Web Services.
All procedures are automatically available. To enable Execute SQL Statement or the ProcessString event handler, uncomment appropriate lines in the service-ctx.xml file.
In version 6.5 or 6.6: Options are individually configured in Web Builder.

In versions 5.0 through 6.0: Procedures can be hidden by naming with

_HIDE suffix.

Default port numbers
9680 (standard non-secure)

9681 (secure)

8081 (Java)

80 (.NET)

WSDL document location URL
In addition to the URLs supported in version 7.0+:

List of WSDL documents available at
http://<session server>:9680.

Links to WSDL list in Administrative Console > Server Properties > Web Services.

Links to model (non-pooled) and pool WSDLs are available in Administrative Console > Model or Pool Properties > Web Services > Show WSDL.


List of WSDL documents for deployed models: http://<session server>:9680/vhi-ws

Connect to model (non-pooled):

http://<session server>:9680/vhi-ws/model/<model name>?wsdl

Connect to session pool:

http://<session server>:9680/vhi-ws/session/<pool name>?wsdl

See also Version 7.x Naming Tip below.

Java web service:

http://<host name>:8081/axis/services/<project name>?wsdl

.NET web service:

http://<host name>/<project name>/<project name>.asmx?wsdl

The session server, model, and connection method is specified in Project Properties.


WSDL target namespace
See Technical Note 10148
WSDL schema organization
Single embedded schema that uses the WSDL namespace, for compatibility with Verastream Process Designer and other BPEL technologies based on Apache ODE 1.3.x.
Java web services in version 6.6.189 and earlier have two embedded schemas in the WSDL with two different namespaces.
Web service client for testing
See Testing Web Services in Version 7.1

Version 7.1: See Testing Web Services in Version 7.1

Version 7.0: Use third-party tools, such as SoapUI, to import the WSDL and submit requests.



Test client automatically generated by Web Builder (runClient.bat for Java; web application for .NET)
Method timeout (how long the connector waits for response from session server)
See Technical Note 10044
Domains (multiple session servers in a VHI load distribution domain)
Edit the plugin-cfg.xml file (as described in Configuring Version 7.1.1142 below) to configure the domainName key (and serverName for a non-local management server, or management server cluster failover name as described in Technical Note 10103). Alternatively, you can specify DomainName and ServerName environment variables in your SOAP request, which takes precedence over the global configuration in the plugin-cfg.xml file.

Edit the service-ctx.xml file (as described in Configuring Version 7.0 through 7.1.221 below) to uncomment and configure the domainName property (and serverName for a non-local management server, or management server cluster failover name as described in Technical Note 10103). Alternatively, you can specify DomainName and ServerName environment variables in your SOAP request, which takes precedence over the global configuration in the service-ctx.xml file.

In Web Builder project properties, select the connect method “Connect to model via domain” or “Connect to session pool via domain.”
WS-I compliance
Yes
Yes (version 6.6); can also support older non-compliant Microsoft Data Set return type.

Additional Information

The following notes expand on references in the table above.

Version 7.x Naming Tip

Beginning in version 7.0, model names are automatically used in the WSDL URI and target namespace. For the widest compatibility with third-party web service clients, avoid spaces in model names and session pool names (use hyphens, underscores, or mixed case instead).

Testing Web Services in Version 7.1

Beginning in version 7.1, Web Services Explorer is a web service client you can use to test the automatic web services, thereby eliminating the need to use a third-party client such as SoapUI. Web Services Explorer web application functionality is provided by the Management Server component. To access Web Services Explorer, use any of the following methods:

  • Click the “Test” button displayed by Design Tool after successfully deploying a model
  • Click the “Test” link displayed in the list of WSDLs for deployed models at http://<session server>:9680/vhi-ws
  • In a web browser, open the following URL:
http://<management server>:8095/wsexplorer/wsexplorer.jsp?com.attachmate.eclipse.wst.ws.explorer=0&mode=standalone&wsdl=http://<session server>:9680/vhi-ws/model/<model name>?wsdl

For more information on using Web Services Explorer, see http://docs2.attachmate.com/verastream/vhi/7.1/en/topic/com.attachmate.vhi.help/html/reference/web_service_test.xhtml.

Note: Web Services Explorer does not support testing web services that are protected by WS-Security, Basic Authentication, or HTTPS encryption features. If you have these options enabled in the web services SOAP stack configuration, use a third-party client for testing.

Configuring Version 7.1.1142

Beginning in version 7.1.1142 (7.1 Service Pack 1), web services configuration can be accomplished in Administrative Console. (The service-ctx.xml file is no longer used for web services configuration as it was in versions 7.0 through 7.1.221.)

Some options not available in Administrative Console are configurable in other XML files located in the AttachmateVerastreamHostIntegratorsesssrvrserviceswsMETA-INF directory. Note: These XML files are created after web services are initially configured.

The following values are configurable in the service-cfg.xml file:

Description
Key
Original Default
HTTP web service port
hostPort
9680
HTTPS web service port
secureHostPort
9681
HTTP basic authentication for client user authorization without WS-Security
authnMetadata and authnService
false

The following values are configurable in the plugin-cfg.xml file:

Description
Key
Original Default
Session server load distribution domain
domainName
(null)
Non-local management server for load distribution domain
serverName
localhost

Note: After saving changes to these files, you must restart the session server service to for changes to take effect. For information on manually restarting the service, see Technical Note 10004.

Configuring Version 7.0 through 7.1.221

To configure version 7.x web services, edit the service-ctx.xml file located in the following directory:

Windows:C:Program FilesAttachmateVerastreamHostIntegratorsesssrvrserviceswsMETA-INF

UNIX:hostintegrator/lib/container/services/ws/META-INF

For example: To configure different port numbers, change value for the hostPort or secureHostPort properties.

After saving changes to this file, you must restart the session server service to for changes to take effect. For information on manually restarting the service, see Technical Note 10004.

Note: When you upgrade to a later version (hotfix or major release) in the future, the service-ctx.xml file may revert to new defaults. It is recommended that you make a backup copy of your edited service-ctx.xml file. After upgrading in the future, use the backup copy as a guide for editing the installed service-ctx.xml file.

Encryption in Version 7.x

Regarding SSL encryption security in version 7.x:

  • To add a CA-signed certificate for SSL, place it in the server keystore using the Java JSSE keytool. If no certificate exists in the HostIntegratorsesssrvretc directory, a self-signed certificate is generated for non-production purposes.
  • To disable the non-secure HTTP port:

Version 7.1.1142: Uncheck “Enable HTTP Web Services” in Administrative Console > Perspective > Host Integrator > Session Servers > Installation > Servers > your server name > Properties > Web Services.

Versions 7.0 through 7.1.221: Edit the service-ctx.xml file to change the httpEnabled property to false.

Note: Verastream Process Designer R3 does not support connections to encrypted web services.

Authentication and Authorization in Version 7.x

Regarding client authentication security in version 7.x, see Connection C in Technical Note 10151.

Stateful Web Services in Version 7.x

Regarding stateful web services in version 7.x:

Disabling WS-Resource in Version 7.1

For compatibility with some technologies, WS-Resource (Web Services Resource 1.2 Framework) can be disabled in the embedded web service configuration. To disable this feature, see Technical Note 10130.

Upgrading to Version 7.x

If you have an existing Java or .NET web service project in Web Builder, you can continue to re-build and re-deploy it after upgrading to version 7.x.

By default, Web Builder no longer supports creating new web service projects. If you need to enable the deprecated web service project types for new Web Builder projects, please contact Support at http://support.attachmate.com/contact/.

If your web service project is based on a user-defined project type (rather than an installed standard project type), see also Technical Note 10120.

If your existing web service project (created in version 6.6.188 or earlier) does not display in Web Builder version 7.0.961, complete the following steps:

  1. In Web Builder version 7.0.961, right-click the project and click Explore. This will open the project folder, such as C:Program FilesVerastreamHostIntegratorprojects<project name>.
  2. In a text editor, open the project.properties file.
  3. Add the following line:
targetnamespace=myvalue

where myvalue is any non-blank string, such as the project name or urn:xmlns:attachmate:vhi-wb-ws:<project name> (the default value for new web service projects in version 6.6.189 or higher).

  1. Close and re-open the Web Builder application.

Related: