Configuring OpenSwitch using the GUI tool

The standalone configuration tool requires a JRE version of 1.4 or later; verify that JAVA_HOME is set to a JRE version of 1.4 or later.

Run the configuration utility for each OpenSwitch that you install; for example, in a mutually aware implementation, you will have two separate OpenSwitch installations and you must run the configuration tool for both installations.

When you run the configuration utility in a multiple OpenSwitch environment, keep in mind which OpenSwitch you are configuring; that is, the primary or secondary OpenSwitch.

Starting the configuration tool

When the installation is successful, click Next, then click Next again when asked if you want to configure OpenSwitch. The configuration tool starts automatically.

If you did not configure OpenSwitch during installation, use this procedure to start the configuration tool.

Before you launch the configuration tool, redirect the GUI display. See “Redirecting to a GUI display”.

Go to the $SYBASE directory and source the SYBASE.csh or SYBASE.sh file. For the C shell, enter:
```
source SYBASE.csh
```
For the Bash, the Bourne, or the Korn shell, enter:
```
. ./SYBASE.sh
```

Set the JAVA_HOME environment variable. For example:

setenv JAVA_HOME $SYBASE/uninstall/OSWSuite/JRE-1_4

Enter:
```
$OPENSWITCH/CFG-1_0/bin/oswcfg.sh
```

Configuring OpenSwitch

The first configuration window displays the directory where OpenSwitch is installed. Click Next.

Complete the options in the OpenSwitch Components section:

Option	Required?	Description
Server Name	Yes	Enter the name of this OpenSwitch server; as many as 32 alphanumeric characters.
Host Name	Yes	This option is automatically set for you to the name of the machine where OpenSwitch is installed. Accept the default.
Port Number	Yes	Enter the port number on which the OpenSwitch server listens for incoming connections. The port number can be any numeric value from 1025 to 65535, and cannot be in use by another process.

Option

Required?

Description

Server Name

Yes

Enter the name of this OpenSwitch server; as many as 32 alphanumeric characters.

Host Name

Yes

This option is automatically set for you to the name of the machine where OpenSwitch is installed. Accept the default.

Port Number

Yes

Enter the port number on which the OpenSwitch server listens for incoming connections.

The port number can be any numeric value from 1025 to 65535, and cannot be in use by another process.

In the Coordination Module section, select:

Custom Coordination Module – if you are going to use a coordination module (CM) in your OpenSwitch installation.

Replication Coordination Module – if you are going to use a replication coordination module (RCM) in your OpenSwitch installation.

See “Planning the configuration” for additional software required when you use an RCM.

None – if you are not going to use a CM or RCM.

Complete the options in the Authorization section:

Option	Required?	Description
Admin User Name	Yes	Enter `sa` (the recommended OpenSwitch administrator’s user name) or another login name for the administrative user. An administrative user has no outgoing connection to the remote Adaptive Server and is intended to perform only administrative tasks.
Admin Password	Yes	Enter `sa` (the recommended OpenSwitch administrator’s password) or another password for the administrative user name. WARNING! For security, change the password to something other than “sa.”
Coord. User Name	No	If you are not using CMs, leave this option blank. If you are using CMs, enter `switch_coord` (the recommended coordination module user name). This name must be different than the Admin User Name value.
Coord. Password	No	If you are not using CMs, leave this option blank. If you are using CMs, enter `switch_coord` (the recommended coordination module password). This password must be different than the password for the Admin User Name.

Answer the questions in the Other Information section:
- Encrypt User Names and Passwords? – to encrypt all user names and passwords in OpenSwitch (and in RCM, if configured).
- Use Mutual Aware Support? – if you are going to implement a mutually-aware setup. See the OpenSwitch Administration Guide for information about this feature.
  
  See “Planning the configuration” for additional software required by this feature.
- Is This the Primary Companion OpenSwitch? – available only when “Use Mutual Aware Support” is selected. If this OpenSwitch server is the primary companion (that is, the primary OpenSwitch server responsible for updating the Adaptive Server OpenSwitch configuration table and for switching over the direction of the Replication Server when failover occurs, if an RCM is used) in a mutually-aware implementation.
Click Next to save the entries and continue.

If you did not select “Use Mutual Aware Support” in step 5, go to step 9.

If you selected “Use Mutual Aware Support” in step 5, complete the Companion OpenSwitch Components options that display in the Mutual Aware Support dialog box:

Option	Required?	Description
Server Name	Yes	Enter the name of the companion OpenSwitch (primary or secondary) in the OpenSwitch cluster. If you select “Is This the Primary Companion OpenSwitch?” enter the server name of the secondary OpenSwitch. If you did not select “Is This the Primary Companion OpenSwitch?” enter the server name of the primary OpenSwitch.
Host Name	Yes	Enter the name of the machine on which the companion OpenSwitch is installed.
Port Number	Yes	Enter number of the port on which the companion OpenSwitch listens.
Admin User Name	Yes	Enter the user name that the administrator uses to log in to the companion OpenSwitch.
Admin Password	Yes	Enter the password for the administrator login used to connect to the companion OpenSwitch.
Cluster Name	Yes	Enter the logical name of the cluster where the two OpenSwitch servers reside in a mutually-aware configuration. WARNING! The Cluster Name value must be the same for both mutually-aware OpenSwitch servers.

Click Next to save the entries and continue.

When the Data Server Maintenance dialog box displays, complete the options in the Config Level Connection Monitor (CMON) section.

The OpenSwitch Connection Monitor (CMON) thread monitors Adaptive Servers and asynchronously notifies threads as soon as connectivity to the remote server is lost.

Option	Required?	Description
User Name	Yes	The login used by the CMON thread to connect to the back-end server. This must be an existing, valid login on each Adaptive Server. Verify that this user has basic privileges.
Password	Yes	Enter the password for the user name you just entered.

Complete the options in the Data Server Components section to add a data server for each Adaptive Server in your OpenSwitch implementation.

Option	Required?	Description
Server Name	Yes	Enter the name of the primary or secondary data server. In a mutually-aware implementation, you must use the same name for an Adaptive Server when you install the Adaptive Server and when you reference the name here for both the primary and secondary OpenSwitch server configuration. Specifically, the name of an Adaptive Server (for example, A1), must be “A1” in the SERVER section of both the primary and secondary OpenSwitch server configuration files and must be A1 in the sql.ini or interfaces file.
Host Name	Yes	Enter the name of the machine on which the data server is installed.
Port Number	Yes	Enter the port number of the data server.
Create Mutual Aware Cluster Table in This Data Server?	No	This selection is available only when you select “Use Mutual Aware Support?” When you use mutually-aware support, OpenSwitch can create a configuration table in Adaptive Server that is updated with server and pool status and is used as another resource to keep the two mutually-aware OpenSwitch servers in sync. To create an OpenSwitch configuration table in this Adaptive Server, select this option. Both OpenSwitch servers in a mutually-aware configuration can access this table. See the OpenSwitch Administration Guide for details about this feature.
Use Different CMON User Name & Password?	No	To use a different CMON user name and password for this data server, select this option, then enter the user name and password in the next two fields. If you do not select this option, the data server you add uses the CMON user name and password that you entered previously.
CMON User Name	No	Enter the CMON user name that is used to log in to this data server.
CMON Password	No	Enter the CMON password that is used to log in to this data server.
Server Name, If Clustered	No	Enter the name of the companion data server if this is Adaptive Server is enabled for high availability. This name is entered under the “hafailover” entry in the sql.ini or interfaces file for this data server.
Port Number, If Clustered	No	Enter the port number of the companion data server if this is an high availability Adaptive Server

Click Add Data Server, then click OK when the confirmation message displays.
Repeat steps 10 and 11 for the other data servers in your OpenSwitch configuration. (OpenSwitch requires at least two data servers.)

To remove a data server, enter the data server’s name and click Remove Data Server. You can only remove a data server that was added using this dialog box.
Click Next to save the entries and continue. The Pool Maintenance dialog box displays.

You must create at least one pool. The options on this window allow you to add or remove pools and to add or remove data servers from a specified pool.

A pool is a logical group of servers within OpenSwitch. A pool can contain zero or more servers that are treated as a self-contained failover group, so all connections within the group fail over only to servers defined within the group. See Chapter 2, “Concepts and Procedures,” in the OpenSwitch Administration Guide for more information about pools.
Complete the options in the Add Pool section:
1. Enter a pool name and click Add Pool.
2. Click OK when the confirmation message displays.
3. Repeat this process until you have created the necessary pools for your implementation.
To remove an existing pool, enter the pool’s name and click Remove Pool. You can only remove a pool that was added using this dialog box.
Add each data server to a pool:
1. Complete these options:
  - Pool Name – select the pool to which you are adding a data server. You can only add a data server to a pool that you have added in this dialog box.
  - Server Name – select the data server that you want to add to the selected pool. You can only add data servers that were added using the Data Server Maintenance dialog box.
2. Click Add Data Server To the Pool, then click OK when the confirmation message displays.
3. Repeat step 15 for each data server in your implementation.
The order in which you add a data server to a pool is important, because the first server that you add becomes the primary data server for the pool, and the second server that you add becomes the secondary—or backup—data server for the pool.

If you are using a mutually-aware environment, you should add two pools, and then add the data servers to each of the pools in reverse order. For example, if you have added POOL1 and POOL2, add ASE1 followed by ASE2 to POOL1, and ASE2 followed by ASE1 to POOL2.

To remove a data server from a pool, select the pool, select the data server, and click Remove Data Server From Pool.
Click Next to save your entries and continue.

If you did not select “Replication Coordination Module” in the second configuration window, go to step 26.

If you selected “Replication Coordination Module” in the second configuration window, the Replication Coordination Module dialog box displays.

The replication coordination module (RCM) is an OpenSwitch coordination module that coordinates the failover of a high availability, warm standby environment. The term “failover” in this document refers, in the general sense, to automatically switching to a redundant or standby server when the currently active server fails or terminates abnormally. It does not refer to Sybase Failover, which is a specific feature of Adaptive Server Enterprise.

A redundant high availability, warm standby environment includes:

A Replication Server configured for warm standby replication
Two Adaptive Servers and corresponding databases
Two OpenSwitch servers
Two RCM instances configured to coordinate failover through the OpenSwitch servers

See the OpenSwitch Coordination Module Reference Manual for requirements and instructions on using a redundant high availability, warm standby environment.

Complete the options in the Replication Coordination Module (RCM) section or accept the defaults:

Option	Required?	Description
Name	Yes	The name of the RCM. The default value is OpenSwitch_ServerName_rcm.
RCM Path	Yes	The location of the OpenSwitch installation directory for the RCM. The default location is $OPENSWITCH/bin/rcm.exe.
Config File	Yes	The location of the RCM configuration file. The default location is $OPENSWITCH/config/OpenSwitch_ServerName_rcm.cfg.
Log File	Yes	The location of the RCM log file. The default location is $OPENSWITCH/logs/OpenSwitch_ServerName_rcm.log.
Is This a Secondary RCM?	Required only if this RCM is a secondary RCM in a mutually-aware or redundant setup.	Select this option if this RCM is a secondary RCM in a mutually-aware setup.
Is This a Redundant Environment Setup?	Required only if this is a redundant RCM environment	This option is enabled only if you did not select mutually-aware support on the first configuration screen. You are automatically assumed to have a redundant environment setup if you selected mutually-aware support and are using RCM. Select this option if this is a redundant RCM environment.

Complete the options in the Replication Server section:

Option	Required?	Description
Server Name	Yes	The name of the Replication Server that controls the warm standby environment. Enter any valid alphanumeric name up to 32 characters.
Host Name	Yes	The host of the Replication Server that controls the warm standby environment. Enter any valid alphanumeric name.
Port Number	Yes	Enter the port number of the Replication Server.
User Name	Yes	Enter user name that is used to log in to the Replication Server. This user should have permission to execute Replication Server commands like switch_active, suspend log transfer from all, and so on.
Password	No.	Enter the password for the user name that is used to log in to the Replication Server. The password displays in the field as asterisks.

Enter the logical connection name. This should be in the form logical dataserver.logical database and must be already configured in the warm standby Replication Server environment; for example, “lds.ldb”.
Click Next to save your entries and close the dialog box.

If you did not select “Is This a Redundant Environment Setup?” in the Replication Coordination Module dialog box, go to step 26.

If you selected “Is This a Redundant Environment Setup?” in the Replication Coordination Module dialog box, the Primary OpenSwitch Information window or the Secondary OpenSwitch Information window opens, depending on whether this is a secondary RCM setup.

The information from this dialog box is saved to the interfaces file and required for the redundant environment setup (two OpenSwitch servers, two RCMs, and two Adaptive Servers) to work properly.

When the {Primary | Secondary} OpenSwitch Information window displays, complete the options in the OpenSwitch Components section. Enter the information or accept the defaults:

If this is a secondary RCM setup, the default information is for the primary OpenSwitch.

WARNING! If the primary OpenSwitch is not up and running, a warning displays. At the end of the configuration, the secondary RCM does not start, but the RCM configuration file is created. The secondary RCM cannot start if the primary OpenSwitch is not running.
If this is not a secondary RCM setup, the default information is for the secondary OpenSwitch.

Option	Required?	Description
Server Name	Yes	The name of the primary or secondary OpenSwitch.
Host Name	Yes	The name of the machine on which the primary or secondary OpenSwitch is installed.
Port Number	Yes	Enter the port number of the primary or secondary OpenSwitch server.

Click Next to continue.

When the RCM Warm Standby Configuration window opens, complete the options in the Active Data Server Configuration section.

This window determines which data server is the active data server and which is the standby data server in the Replication Server warm standby environment.

Option	Required?	Description
Server Name	Yes	Select the name of the active data server in the warm standby environment. This server cannot be the same server as the one you select for the standby data server in the next section. You must have already added this data server in step 10, in the Data Server Maintenance dialog box, Data Server Components section.
User Name	Yes	The user name used by the RCM to log in to the active data server. This user must have permission to execute commands like use database, sp_start_rep_agent, and so on.
Password	No	Enter the password for the user name you entered. The password displays in the field as asterisks.

Complete the options in the Standby Data Server Configuration section.

Option	Required?	Description
Server Name	Yes	Select the name of the standby data server in the warm standby environment. This server cannot be the same server as the one you selected for the active data server in the previous section. You must have added this data server in step 10, in the Data Server Maintenance dialog box, Data Server Components section.
User Name	Yes	The user name used by the RCM to log in to the standby data server. This user must have permission to execute commands like use database, sp_start_rep_agent, and so on.
Password	No	Enter the password for the user name you entered. The password displays in the field as asterisks.

Select the name of the application pool in the RCM environment, then click Next to continue.

When the Failure Action dialog box displays, complete the options, or click Next to go to the next configuration dialog box. Some options are required only if you selected “Use Mutual Aware Support.”

Option	Required?	Description
Connection Monitor Failure – Action to Take	No	Select the action to perform when there is failure in the Connection Monitor: DEFAULT – starts the CMON thread in the next available server in that pool. CUSTOM – runs a user-defined custom script. MANUAL – runs a manual script to notify the system administrator that some manual action is required. CUSTOM_MANUAL – run a custom script. The manual script runs if the custom script fails. See the OpenSwitch Administration Guide for more information.
Network Failure – Action to Take	Only if “Use Mutual Aware Support” is selected	Select the action to perform when there is network failure: DEFAULT – the primary companion OpenSwitch is shut down and all-clients connected to the primary companion OpenSwitch are reconnected to the secondary companion OpenSwitch in the same cluster. Configuration changes (including server and pool status changes) are permitted. CUSTOM – run a custom script. MANUAL – run a manual script. CUSTOM_MANUAL – run a custom script. The manual script runs if the custom script fails. See the OpenSwitch Administration Guide for more information.
Companion Failure – Action to Take	Only if “Use Mutual Aware Support” is selected	Select the action to perform when the companion in a mutually-aware implementation fails: DEFAULT – mark the companion server as unreachable, start a timer to ping it from time to time, and act as if the primary OpenSwitch is the only server. Once the connection to the companion is reestablished, the two OpenSwitch servers synchronize their configurations CUSTOM – run a custom script. MANUAL – run a manual script. CUSTOM_MANUAL – run a custom script. The manual script runs if the custom script fails. See the OpenSwitch Administration Guide for more information.
Data Server Failure – Action to Take	Only if “Use Mutual Aware Support” is selected	Select the action to perform when a data server fails: DEFAULT – mark the Adaptive Server as not running and initiate a failover process. CUSTOM – run a custom script. MANUAL – run a manual script. CUSTOM_MANUAL – run a custom script. The manual script runs if the custom script fails. See the OpenSwitch Administration Guide for more information.
User Action: Custom Script Manual Script	Yes, but only when any of the previous options in this dialog box are set to something other than “Default”	Enter the name of the custom script to execute if one of the previous options is set to CUSTOM or CUSTOM_MANUAL. Enter the name of the script to execute when one of the previous options is set to MANUAL or CUSTOM_MANUAL. See the OpenSwitch Administration Guide for more information.

Click Next to continue.
The Summary window appears, with the following button options:
- Back – returns you to the previous screens to make any modifications in the screens.
- Finish – begins the final configuration process, and displays a progress bar while the OpenSwitch server is being configured. Selecting Finish disables the Back button, and changes the Cancel button to an Exit button.
- Cancel – allows you to stop the configuration process. Once the Cancel button changes into an Exit button and you have finished the configuration process, select Exit to exit out of the Configurator utility.
When the Summary window appears, click Finish. A progress bar displays as the OpenSwitch server is being configured.
When a message displays indicating that the configuration was successful, click OK, then click Exit to exit the configuration tool and close the installer window.

If the configuration was not successful, use a text editor to view the configuration log (osw.err), which is located in the OpenSwitch logs directory.

OpenSwitch does not provide any localized messages besides English. However, you can still use OpenSwitch in a different language environment, because the installer copies the English messages to all the different language locales directory during the installation. Therefore, when you execute OpenSwitch in a non-English environment, the messages returned to the client is in English.