Enabling a proxy server using virtual hostnames or IP addresses

When you set up your proxy server, on each client accessing the cluster, you create and maintain a proxy.conf file that maps the IBM® Spectrum Symphony management hostnames or IP addresses to the proxy server, allowing a client to discover the management hosts to which to connect. If your hosts (or their names or IP addresses) change frequently (for example, hosts can change when an IBM Spectrum Symphony cluster is deleted and re-provisioned, changing the hostnames or IP addresses for the management hosts), use virtual hostnames and IP addresses, which are static and do not change. Set the virtual information once in each of the client-side proxy.conf files, and avoid having to maintain proxy server configuration if management host hostnames or IP addresses change later on.

About this task

Alternatively, if your hosts do not change, then consider using physical hostnames and IP addresses instead.

Note that you can use virtual hostnames or IP addresses in the file for the IBM Spectrum Symphony session director (SD) and session manager (SSM). For other services (such as VEMKD, EGO service controller, and repository server (RS)), use physical host information.

To use virtual information with your proxy server, you use each IBM Spectrum Symphony management host's virtual hostname or IP address, record that information in a readable file on the management host, and then associate that file in the sd.xml configuration file.

Procedure

Prepare a virtual information file about each management host. On each management host:
1. Determine the host's virtual hostname or IP address.
2. Create a file that specifies this virtual information for the host.
  Ensure that this virtual information file:
  - Is a readable file, since the IBM Spectrum Symphony session director (SD) and session manager (SSM) will need access to read it.
  - Contains the management host's unique static virtual hostname or IP address. This host name or IP address must be the first line in the file. For example, if the virtual IP address is 10.123.11.11, then the entire file is single line containing:
    10.123.11.11
    If the virtual hostname is virtHost1, then the entire file is single line containing:
    virtHost1
  - Is saved and kept on the management host. The contents (virtual hostname or IP address) should be unique for each host; the file name should be the same for all hosts. For example, if you save this virtual information file as /opt/myVirtFile, use that file name as the virtual information file on all management hosts. This way, when you specify the SD_VIRTUAL_HOSTNAME_FILENAME environment variable value in the sd.xml file, the system knows to always look in the /opt/myVirtFile file for virtual information for the host.
  Remember this virtual information file name, as you will specify it when you set up the SD_VIRTUAL_HOSTNAME_FILENAME environment variable configuration for the sd.xml file later on (in step 3).
Prepare the proxy server configuration file for each client:
1. Create a proxy server configuration file, called proxy.conf, with the proxy server host information (with a fixed hostname or IP address) and information for each IBM Spectrum Symphony management host (with the virtual host name or IP address of each SD and SSM host).
  For example, with the following configuration in the proxy.conf file, IBM Spectrum Symphony packages are sent to the proxy server (proxyHost) instead of to the IBM Spectrum Symphony hosts (virtHost1 and virtHost2) for SD and SSM:
```
#VEMKD
proxyHost:7870 symHost1:7870
proxyHost:9870 symHost2:7870

#EGO_SERVICE_CONTROLLER
proxyHost:7872 symHost1:7872
proxyHost:9872 symHost2:7872

#RS
proxyHost:7873 symHost1:7873 
proxyHost:9873 symHost2:7873 

#SD
proxyHost:7874 virtHost1:7874
proxyHost:9874 virtHost2:7874
proxyHost:7875 virtHost1:7875
proxyHost:9875 virtHost2:7875

#SSM
proxyHost:31000-32000 virtHost1:31000-32000
proxyHost:41000-42000 virtHost2:31000-32000
```
  Note that the lines prefixed with a # symbol are comments for informational purposes only. If you include comments, add them on a separate line.
2. Copy your proxy.conf file to the EGO_CONFDIR directory on the client.
  
  Important: Do not copy the proxy.conf file to the EGO_CONFDIR directory on the cluster. If you do, the changes impact the whole cluster.
  
  Tip: If you want to load proxy.conf from a specific location, set the PROXY_PATH environment variable to the desired directory by using the setSymEnvclient client API. If PROXY_PATH is not set, the proxy.conf file is loaded from EGO_CONFDIR.
3. Optional: Configure error detection for the proxy.conf file:
  1. Switch to the following directory:
    - Windows: Installation_top\soam\conf (or %SOAM_HOME%\conf)
    - Linux®: $EGO_TOP/soam/conf (or $SOAM_HOME/conf)
  2. Change the log level in cli.log4j.properties to ALL.
  3. Run the soamview app command for the changes to test for errors.
    If there are errors, check your proxy.conf file and try again.
    
    If IBM Spectrum Symphony cannot find the proxy server information in proxy.conf, it sends network packages to the IBM Spectrum Symphony cluster hosts directly. No error is reported.
Configure the session director to use virtual information. On the primary and on each primary candidate host:
1. Open the sd.xml configuration file:
  - Windows: %EGO_CONFDIR%\..\..\eservice\esc\conf\services\sd.xml
  - Linux: $EGO_CONFDIR/../../eservice/esc/conf/services/sd.xml
2. Associate the virtual information file (created in step 1) by adding the SD_VIRTUAL_HOSTNAME_FILENAME environment variable with your virtual information file name:
```
<ego:EnvironmentVariable name="SD_VIRTUAL_HOSTNAME_FILENAME">filename</ego:EnvironmentVariable>
```
  For example, if you created the /opt/myVirtFile file, specify:
```
<ego:EnvironmentVariable name="SD_VIRTUAL_HOSTNAME_FILENAME">/opt/myVirtFile</ego:EnvironmentVariable>
```
3. Associate the ports for virtual information file by configuring the SD_ADMIN_PORT, SD_SDK_PORT, and SSM_SDK_ADDR environment variables with the ports redirected by your proxy server:
```
<ego:EnvironmentVariable name="SD_ADMIN_PORT">port</ego:EnvironmentVariable>
<ego:EnvironmentVariable name="SD_SDK_PORT">port</ego:EnvironmentVariable>
<ego:EnvironmentVariable name="SSM_SDK_ADDR">port</ego:EnvironmentVariable>
```
  For example:
```
<ego:EnvironmentVariable name="SD_ADMIN_PORT">7874</ego:EnvironmentVariable>
<ego:EnvironmentVariable name="SD_SDK_PORT">7875</ego:EnvironmentVariable>
<ego:EnvironmentVariable name="SSM_SDK_ADDR">12001-12100</ego:EnvironmentVariable>
```
4. Start the cluster and enable your IBM Spectrum Symphony application:
```
egosh ego start all
soamcontrol app enable application_name
```
  The session director will use virtual information file (specified in the SD_VIRTUAL_HOSTNAME_FILENAME environment variable) to get the virtual configuration information from the sd.xml file.
5. Check that SD_ADMIN_VIRTUAL and SD_SDK_VIRTUAL information is created for the client:
```
egosh client view SD_ADMIN_VIRTUAL
egosh client view SD_SDK_VIRTUAL
```
  In the command results, look for virtual host names or IP addresses.
Set the clients to use the virtual information, instead of the physical information. On each client:
1. Ensure connection to IBM Spectrum Symphony, and that the client can send workload to the cluster to test and verify components, using the virtual information. Run the symping command with SOAM_USE_VIRTUAL_HOSTNAME=Y, and ensure that the command returns error free:
  - On Windows:
```
set SOAM_USE_VIRTUAL_HOSTNAME=Y
symping
```
  - On Linux:
```
export SOAM_USE_VIRTUAL_HOSTNAME=Y
symping
```
2. Ensure connection to the IBM Spectrum Symphony SOAM commands (such as soamdeploy, soamcontrol, soamreg, soamunreg, soamview, soamlogon, and soamlog), using the virtual information. Run the following commands with SOAM_USE_VIRTUAL_HOSTNAME=Y, and ensure that the commands return error free:
  - On Windows:
```
set SOAM_USE_VIRTUAL_HOSTNAME=Y
soamview app
```
```
set SOAM_USE_VIRTUAL_HOSTNAME=Y
soamcontrol
```
```
set SOAM_USE_VIRTUAL_HOSTNAME=Y
soamreg
```
```
set SOAM_USE_VIRTUAL_HOSTNAME=Y
soamunreg
```
```
set SOAM_USE_VIRTUAL_HOSTNAME=Y
soamlog
```
```
set SOAM_USE_VIRTUAL_HOSTNAME=Y
soamlogon
```
  - On Linux:
```
export SOAM_USE_VIRTUAL_HOSTNAME=Y
soamview app
```
```
export SOAM_USE_VIRTUAL_HOSTNAME=Y
soamcontrol
```
```
export SOAM_USE_VIRTUAL_HOSTNAME=Y
soamreg
```
```
export SOAM_USE_VIRTUAL_HOSTNAME=Y
soamunreg
```
```
export SOAM_USE_VIRTUAL_HOSTNAME=Y
soamlog
```
```
export SOAM_USE_VIRTUAL_HOSTNAME=Y
soamlogon
```
Before running the egosh service command on management hosts, set the EGO_SC_HOST and EGO_SC_PORT environment variables to ensure that the command works appropriately after enabling your proxy server with virtual hosts:
```
export EGO_SC_HOST="$virtualIP1 $virtualIP2" export EGO_SC_PORT=$ESC_PORT
```
where:
$virtualIP1 $virtualIP2
The virtual IP addresses configured for the primary and primary candidate hosts in the previous steps. Separate the two IP addresses by a space. If you do not have primary candidate hosts, then set only the virtual IP address for the primary host:
export EGO_SC_HOST="$virtualIP" export EGO_SC_PORT=$ESC_PORT
$ESC_PORT

The egosc (EGO service controller) port. This port is automatically assigned from the base port at installation; the default port is 7872, and must be enabled for TCP ports.

What to do next

If you require disabling the proxy server, remove the proxy.conf file from the EGO_CONFDIR directory on the client.