Configuration Server Proxy

Using Configuration Server Proxy increases the robustness of the whole system, decreases the number of client connections to Configuration Server, and minimizes network traffic. That is, existing clients can continue, and new clients start, their operations when Configuration Server fails. In addition, after Configuration Server recovers, the client reconnect takes far less time than if all clients were directly connected to Configuration Server.

Configuration Server Proxy is an Application of the Configuration Server type operating in a special mode. As such, it replaces Configuration Server seamlessly for the clients. You can also configure Configuration Server Proxy permissions so that clients of a particular proxy access only the part of the configuration environment relevant to their site. See User Authorization and the ''Genesys 8.1 Security Deployment Guide'' for more information about setting permissions.

How it Works

In a distributed configuration environment, the master Configuration Server is running at the site where the Configuration Database is located. Configuration Server Proxies at multiple remote sites are connecting to the master Configuration Server.

Instead of sending all the requests to Configuration Server, Configuration Server clients that require read-only access to Configuration Server can operate with one or more Configuration Server Proxies. Configuration Server Proxy passes messages to and from Configuration Server. Moreover, the proxy keeps the configuration data in its memory and responds to client data requests. Any configuration data updates are passed immediately to Configuration Server Proxy, so that it is always up to date; no additional configuration is required to specify an update interval.

Configuration Server Proxy Functions

• Receives subscription requests from clients and handles them without passing the requests to Configuration Server.
• Stores in internal memory all configuration data it receives from Configuration Server.
• Receives notifications on data changes from Configuration Server, updates internal memory, and passes notifications to clients.
• Receives read-data requests from clients and responds to them using the data stored in the internal memory.

Warning

Always run Configuration Server Proxy under the default account Environment\default.

Important

A hierarchical configuration of Configuration Server Proxies-for example, a Configuration Server Proxy application working with another Configuration Server Proxy that operates directly with Configuration Server-is not supported.

Deploying Configuration Server Proxy

Important

To ensure faultless operation, all Configuration Servers in the configuration environment must be running the same release. Configuration Server Proxy may start with a master Configuration Server running a later release, but only during the migration process. Refer to the ''Genesys Migration Guide'' for more information.

Prerequisites

• The Configuration Layer components, including the master Configuration Server, are installed and running as described in Deploying Configuration Layer.
• You are logged in to Genesys Administrator.

Installation and Configuration

1. Configure as many instances of Configuration Server Proxy as needed. [+] Show steps Prerequisite You are logged in to Genesys Administrator. Procedure Go to Provisioning > Environment > Applications, and select New in the toolbar. This opens a Browse dialog box that lists available application templates. If a Configuration Server Proxy template file is not listed, do one of the following: Import the Configuration Server Proxy_<current-version>.apd file from the Management Framework 8.5 product CD. Create a new template using the procedure in [https://docs.genesys.com/Documentation/FR/8.5.0/Dep/StdConf#appTmplts Application Templates, and repeat this step. In the Browse dialog box, select the Configuration Server Proxy template file. In the General section of the Configuration tab: Enter a descriptive name in the Name text box. In the list of Connections, add a connection to the master Configuration Server Application object. If redundant master Configuration Servers are configured, specify a connection to the primary Configuration Server. In the Server Info section: Select the Host object on which this Configuration Server Proxy runs. Specify the Listening Ports that Configuration Server Proxy clients must use to connect to this Configuration Server. In the Working Directory, Command Line, and Command Line Arguments text boxes, do one of the following: Enter the appropriate information in each of the text boxes. For information about command-line parameters, see [[CSProxy#stCSP|Starting Configuration Server Proxy]. Type a period (.) in the Working Directory and Command Line text boxes, and leave the Command Line Arguments text box blank. The information will be filled in automatically when you install Configuration Server Proxy, but only if the Installation Package can connect to the master Configuration Server. Enter appropriate values for the other mandatory fields (those indicated by red asterisks). In the Log On As Account field, you must use the default account, Environment\default. Warning Always run Configuration Server Proxy under the default account Environment\default. (Optional) On the Options tab, do any of the following as required: If you want this Configuration Server Proxy to be writable, set the option proxy-writable in the csproxy section to true. Set the values of the log configuration options. Click Save & Close to save the configuration.

2. Install the corresponding number of Configuration Server Proxies. [+] Show steps Prerequisite The Configuration Server Proxy Application object is created. Installing Configuration Server Proxy on UNIX On the Management Framework 8.5 product CD, locate and open the installation directory appropriate for your environment: For an enterprise (single-tenant) environment, the installation directory is configuration_layer/configserver/single/<operating_system>. For a multi-tenant environment, the installation directory is configuration_layer/configserver/multi/<operating_system>. The installation script, called install.sh, is located in the appropriate directory. Type install.sh at the command prompt, and press Enter. For the installation type, type 3 to select Configuration Server Proxy, and press Enter. To specify the host name for this Configuration Server Proxy, do one of the following: Type the name of the host, and press Enter. Press Enter to select the current host. Enter the Master Configuration Server host name, and press Enter. Enter the Master Configuration Server network port, and press Enter. Enter the Master Configuration Server user name, and press Enter. Enter the Master Configuration Server password, and press Enter. The installation displays the list of Application objects of the specified type configured for this Host object. Type the number corresponding to the Configuration Server Proxy Application object you configured in step 1, and press Enter. To specify the destination directory, do one of the following: Press Enter to accept the default. Enter the full path of the directory, and press Enter. If the target installation directory has files in it, do one of the following: Type 1 to back up all the files in the directory, and press Enter. Specify the path to which you want the files backed up, and press Enter. Type 2 to overwrite only the files in this installation package, and press Enter. Then type y to confirm your selection, and press Enter. Use this option only if the application already installed operates properly. Type 3 to erase all files in this directory before continuing with the installation, and press Enter. Then type y to confirm your selection, and press Enter. The list of file names will appear on the screen as the files are copied to the destination directory. Specify the full path to, and the exact name of, the license file that Configuration Server Proxy will use, and press Enter. When the installation process is finished, a message indicates that installation was successful. The process places Configuration Server Proxy in the directory that you specified during installation. Installing Configuration Server Proxy on Windows Warning Genesys does not recommend installation of its components via a Microsoft Remote Desktop connection. The installation should be performed locally. On the Management Framework 8.5 product CD, locate and open the installation directory appropriate for your environment: For an enterprise (single-tenant) environment, the installation directory is configuration_layer/configserver/single/windows. For a multi-tenant environment, the installation directory is configuration_layer/configserver/multi/windows. The installation script, called setup.exe, is located in the appropriate directory. Locate and double-click setup.exe to start the Genesys Installation Wizard. Use the About button on the wizard's Welcome page to review the read_me file. This file also contains a link to the server's Release Notes file. Click Next. On the Configuration Server Run Mode page, select Configuration Server Proxy. On the Connection Parameters to the Genesys Configuration Server page, specify the host name, port, user name, and password for the Master Configuration Server, then click Next. On the Select Application page, select the name of the Configuration Server Application object that you created in step 1, and click Next. On the Access to License page, specify the license access type and the appropriate parameters, and click Next. On the Choose Destination Location page, the wizard displays the destination directory specified in the Working Directory property of the server's Application object. If the specified path is invalid, the wizard generates a path to C:\Program Files\GCTI\<Singletenant or Multitenant> Configuration Server. If necessary, click: Browse to select another destination folder. In this case, the wizard will update the Application object's Working Directory property in the Configuration Database. Default to reinstate the path specified in the Working Directory property. Click Next to proceed. On the Ready to Install information page, click: Back to update any installation information. Install to proceed with the installation. On the Installation Complete page, click Finish. When the installation process is finished, a message indicates that installation was successful. The process places Configuration Server Proxy in the directory that you specified during the installation process.

3. Modify each Configuration Server Proxy client to work with Configuration Server Proxy. [+] Show steps Prerequisites The Configuration Server Proxy Application object is created. You have identified the client applications that are to operate with this particular Configuration Server Proxy. You are logged in to Genesys Administrator. Important Repeat this procedure for each application that is to be a client of Configuration Server Proxy. Procedure Go to Provisioning > Environment > Applications, and double-click the client Application object that you want to connect to Configuration Server Proxy. In the General section of the Configuration tab, add a Connection to the Configuration Server Proxy to which the client application should connect. Click Save & Close to save the configuration changes. Now, when you start the client application, it will operate with the given Configuration Server Proxy. Start the client application using one of the following methods: From Genesys Administrator. From the command line. In this case, you must use the parameters -host and -port to point to the Configuration Server Proxy with which the application will be operating. Click Save & Close to save the changes.

4. (Optional) Configure redundant Configuration Server Proxies. [+] Show steps Prerequisites A primary Configuration Server Proxy Application object already exists. You are logged in to Genesys Administrator. Procedure Configure an Application object for the backup Configuration Server Proxy as described in step 1 above. Install a backup Configuration Server Proxy as described in step 2, above. In Genesys Administrator, go to Provisioning > Environment > Applications and double-click the primary Configuration Server Proxy client Application object. On the Configuration tab, open the Server Info section. In the Backup Server field, specify the Configuration Server Proxy application you want to use as the backup server. Open the Properties dialog box of the Configuration Server Proxy application that you want to configure as a primary server. In the Redundancy Type field, select Warm Standby. Select Auto-Restart. Click Save & Close to save the configuration changes.

Starting Configuration Server Proxy

Warning

Always run Configuration Server Proxy under the default account Environment\default.

The startup command line for Configuration Server Proxy must identify the:

• Configuration Server Proxy executable file
• Configuration Server Proxy application name (the -app parameter)
• Configuration Server host (the -host parameter)
• Configuration Server port (the -port parameter)
• Configuration Server Proxy license file or license server location (the -l parameter)

Configuration Server Proxy supports the command-line parameters common to Genesys server applications, as described in Starting and Stopping Manually.

Important

If using a primary-backup pair of Configuration Server Proxies, follow the same starting procedure for both primary and backup applications but make sure you specify the correct application name for each.

Starting Configuration Server Proxy on UNIX

Go to the directory in which Configuration Server Proxy is installed, and do one of the following:

• To use only the required command-line parameters, type the following command line: sh run.sh
• To specify the command line yourself, or to use additional command-line parameters, type the following command line:
  confserv -host <Configuration Server host> -port <Configuration Server port> -app <CS proxy application objects name> [<additional parameters and arguments as required>]

Starting Configuration Server Proxy on Windows

Do one of the following:

• Use the Start > Programs menu.
• To use only the required command-line parameters, go to the directory in which Configuration Server Proxy is installed, and double-click the startServer.bat file.
• To specify the command line yourself, or to use additional command-line parameters, open the MS-DOS window, go to the directory in which Configuration Server Proxy is installed, and type the following command line:
  confserv.exe -host <Configuration Server host> -port <Configuration Server port> -app <CS proxy application objects name> [<additional parameters and arguments as required>]

Writable Configuration Server Proxies

By default, Configuration Server Proxy provides read-only access to configuration data. Configuration Server clients that require write access to Configuration Server must still connect directly to Configuration Server. Some of Genesys Supervisor- and Agent-facing applications (such as Workspace Desktop Edition), while deployed in high numbers, require write access to configuration data and should be deployed against Configuration Server Proxy in Writable mode.

Administrative applications, such as Genesys Administrator, should still connect to the Master Configuration Server to perform complex configuration updates, because Configuration Server Proxy is writable mode is not designed to handle all types of configuration updates. Updates made in bulk might result in a significant extra load on the system when done by the Proxy server rather than the Master server.

To configure a Configuration Server Proxy as writable, use the Configuration Server Proxy configuration option proxy-writable. For more information about this option, refer to the ''Framework Configuration Options Reference Manual''.

Redundant Configuration Server Proxies

The high-availability (HA) architecture implies the existence of redundant applications, a primary and a backup, monitored by a management application. Like Configuration Server, Configuration Server Proxy supports the warm standby redundancy type between redundant Configuration Server Proxies. For more information, refer to Redundant Configuration Servers.

Prior to release 8.1.3, when a switchover occurred between the primary and backup Configuration Server Proxies, Configuration Server Proxy clients had to read configuration information anew and reestablish the connections to the backup server themselves. Especially in large configuration environments, this often led to detrimental effects on system performance, leading clients to question the usefulness of the backup proxy server.

Starting in release 8.1.3, client connections are restored automatically by the backup Configuration Server Proxy when it switches to primary mode if the connection between the main Configuration Server and Configuration Server Proxy is lost, because the main Configuration Server is stopped via the Management Layer. This makes the switchover practically invisible to clients, and essentially eliminates the performance impact on the system. This restoration is made possible by the backup Configuration Server Proxy keeping its own record of client connections and disconnections. Under normal conditions, the primary proxy server notifies the backup proxy of client connections and disconnections, which the backup stores in its History Log Database. When the backup switches to primary, it is able to restore client connections based on the connection and disconnection information it has stored.

If the connection between the main and proxy servers is lost, and ADDP is configured between Configuration Server Proxy and the main Configuration Server and also between the proxy server and its client, the session is not restored. Clients of the Configuration Server Proxy must reregister and read all data from scratch.

Important

Two Configuration Server Proxies configured as an HA pair cannot be separated into two standalone servers in runtime. Each of the servers must be stopped, re-configured, and then restarted.

Using Configuration Server Proxy with External Authentication Systems

In distributed systems prior to release 8.0, external authentication was configured only on the Master Configuration Server, and each Configuration Server Proxy passed authentication requests to it. Now, RADIUS and LDAP external authentication, starting in release 8.0 and 8.1, respectively, can be configured on the Master Configuration Server and on each Configuration Server Proxy. Therefore, each Configuration Server Proxy can process authentication requests itself, and does not need to pass them on to the Master Configuration Server. For more information about setting up external configuration on Configuration Server Proxy, refer to the ''Framework 8.5 External Authentication Reference Manual''.

Support for Multi-Language Environments

You do not need to perform any additional configuration to have Configuration Server Proxy support multi-language environments. If the master Configuration Server supports UTF-8 encoded data, all Configuration Server Proxies connected to that master Configuration Server also support UTF-8 encoding. See Multi-language Environments for more information about using UTF-8 encoding to enable multi-language environments.

Configuration History Log

You can configure a history log with Configuration Server Proxy to store historical information about client sessions and changes to configuration objects. Refer to Configuration History Log for more information.

Failure of Configuration Server Proxy

When Configuration Server Proxy fails or disconnects from its clients, the clients attempt to reconnect to Configuration Server Proxy. If it is not available and if a backup Configuration Server Proxy is configured, the clients attempt to connect to the backup.

When Configuration Server Proxy fails, you must restart it manually or use the Management Layer for autorestart.

Failure of Master Configuration Server

When the master Configuration Server fails or the connection to it is lost, the clients of Configuration Server Proxy continue their normal operations. Configuration Server Proxy initiates reconnect attempts to the master Configuration Server. Meanwhile, Configuration Server Proxy responds to client requests using the configuration data stored in its memory.

When the master Configuration Server fails, you must restart it manually or use the Management Layer for autorestart.

The following diagram shows Configuration Server Proxy behavior when a primary-backup pair of master Configuration Servers is configured.

Distributed Installation

When the primary master Configuration Server fails or the connection to it is lost, Configuration Server Proxy initiates reconnect attempts to the master Configuration Server and, if it is not available, to the backup Configuration Server. If the connection to the backup Configuration Server is established, Configuration Server Proxy remains connected to the backup server until:

• The connection to the backup Configuration Server is lost.
• The backup Configuration Server fails.
• Configuration Server Proxy fails or is restarted.