Jump to: navigation, search

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. When Configuration Server is configured, 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 Configuration Server type operating in a special mode. As such, it seemlessly replaces Configuration Server 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 or the Genesys 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.
  • Always run Configuration Server Proxy under the default account Environment\default.
  • 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

  • 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 Framework Migration Guide for more information.
  • When deploying Configuration Server Proxy, keep in mind that redundancy type is critical. Specifically:
    • If Configuration Server Proxy is running as a single proxy server, set the redundancy type to Not Specified.
    • If Configuration Server Proxy is part of a HA pair and/or is configured as a primary or backup, set the redundancy type to Warm Standby.


  • 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
2. Install the corresponding number of Configuration Server Proxies. [+] Show steps
3. Modify each Configuration Server Proxy client to work with Configuration Server Proxy. [+] Show steps
4. (Optional) Configure redundant Configuration Server Proxies. [+] Show steps

Configuring a Dedicated Port for Client User Interface Applications

  • Genesys strongly recommends that you do not restrict the default port to accept only client UI applications. Because the backup Configuration Server communicates with Configuration Server via the default port, and because many other Genesys Server applications cannot operate properly with being connected to the default port, restricting the default port would disable you from using these additional beneficial components.
  • Ports that have been dedicated as HA sync (in the Server Info section of the port's Configuration tab in Genesys Administrator) cannot be provisioned to accept only client UI applications.

Dedicated ports can also be configured on Configuration Server Proxy in the same way that they are configured on the master Configuration Server. Like the master server, the proxy server must sit inside the firewall, as shown in the following illustration:

Dedicated Port on Master Configuration Server Proxy

Use the instructions here to configure the dedicated port.

Starting Configuration Server Proxy

  • Always run Configuration Server Proxy under the default account Environment\default.
  • 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.

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.

If you want to generate logs logging during startup and initialization (referred to as bootstrap logging) of Configuration Server Proxy, start the server from the command line and include the -log-<log option name> <log-type> parameter. Optionally, you can store these logs in a file separate from the operations logs—also include the -log-<log-type> <filename> parameter in the startup command.

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 in 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.

HA Configuration Server Proxy supports ADDP between the pair of proxy servers if ADDP has been enabled between the master Configuration Server and Configuration Server Proxy in the Connections tab of the proxy server. The primary and backup Configuration Server Proxies also use these ADDP settings to communicate with each other.

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 to the backup Configuration Server Proxy when it switches to primary mode, if the connection between the client and primary Configuration Server Proxy is lost, because the primary proxy server is stopped. 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 mode, it is able to restore client connections based on the connection and disconnection information it has stored.

If the connection between the primary and backup servers is lost, prior to switchover, the session is not restored. Clients of the Configuration Server Proxy must reregister and read all data from scratch.

You cannot separate two Configuration Server Proxies configured as an HA pair into two standalone servers at runtime. You must stop, re-configure, and then restart each server.

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 authentication on Configuration Server Proxy, refer to the Framework External Authentication Reference Manual.

Load-Balanced Configuration Server Proxies for Agent-Facing Applications

Starting in release 8.5.1, you can integrate load balancing into a system of Configuration Server Proxies. This enables a group of Configuration Server Proxies to share the processing load (client connections).

The benefits of load-balancing are two-fold:

  • Deploying a pool of Configuration Server Proxies enables you to easily manage environments in which the capacity of a single proxy server is not enough to handle all agent-facing clients (such as with the Workspace Desktop Edition).
    Refer to the Hardware Sizing Guide to determine the capacity of maximum incoming connections for a single Configuration Server Proxy.
  • If any Configuration Server Proxy is not operational, new client connections are not distributed to that proxy server automatically.

High Level Architecture

This solution requires the use of a third-party load balancer (F5). A set of standalone Configuration Proxy Instances are deployed on several hosts, subject to limitations noted in the Hardware Sizing Guide. The resources of each host (memory and number of CPUs) must be sufficient to allow the launching of, and running under load, all instances of Configuration Server Proxy assigned to it. The master Configuration Server maintains a connection to each Configuration Server Proxy. An F5-based hardware load balancer is connected to all of the proxy servers in the group, and provides a single virtual IP address and port to which the clients of those proxies connect.

This can be extended to multiple groups of Configuration Server Proxies, each group served by a different load balancer. This is shown in the following diagram.

Load-Balanced Configuration Server Proxies

Support of Agent-Facing user Interface Applications

The following Genesys application supports working with a pool of Configuration Server Proxies behind a hardware load balancer: Workspace Desktop Edition (formerly called Interaction Workspace).


This solution also has these limitations:

  • Session restoration on the Connection Server Proxy side is not supported in this type of deployment.
  • The built-in Kerberos protection against ticket sniffing by caching used tickets is turned off. Clients are connecting to a pool of servers, and each proxy server has a separate ticket cache.
Support for this solution has been tested by Genesys on a limited number of applications. Connecting unsupported applications to Configuration Server Proxy using a hardware load balancer may result in performance issues and feature degradation. Refer to the documentation for a particular application to confirm that it supports the Configuration Server Proxy load-balancing architecture.


To set up the load-balanced solution, do the following:

  1. Install and configure F5 with VIP, and use the round-robin methodology to distribute connections to clients.
  2. Install and configure the Configuration Server Proxies as individual Application objects of type ConfigurationServer. Do not specify any backup instance, to ensure that all instances are independent from each other.
  3. Create a Host object for the machine associated with the External Configuration Server Proxy, and set its LCA port to 0 (zero).
  4. Configure another Application object of type ConfigurationServer, to create an External Configuration Server Proxy that represents the F5 load balancer. Set its host and port to the values for F5.
  5. Provision all client applications with a connection to the External Configuration Server Proxy. If required, configure ADDP on those connections.
  6. In the [csproxy] section of each Configuration Server Proxy in the proxy pool, set proxy-cluster-name to the name of the External Configuration Server Proxy object. For more information about this option, refer to the Framework Configuration Options Reference Manual.
  7. If you are planning to use Kerberos authentication, do the following:
    • Configure all Configuration Server Proxies in the pool to use the same SPN and the same .keytab file.
    • Set the KRB5RCACHETYPE environment variable to none.
  8. Set each of the proxy servers in the pool to autorestart, to enable Solution Control Server (SCS) to detect application failure and/or host unavailability. Configure any other monitoring features, such as hangup detection, as required. The External Configuration Server Proxy object, representing the F5 load balancer, is not monitored by SCS.

TLS Configuration

To configure TLS between agent-facing Applications and Configuration Server Proxy clusters using the F5 load balancer, do the following:

  1. Obtain Certification Authority (CA) security certificates for each Configuration Server Proxy host and agent-facing client host. Store the certificates in the Trusted Root Certification Authorities Certificates folder. Refer to the Microsoft article Installing a Root Certificate.
  2. Request and obtain security certificates for Server authentication. Make sure that the name in the Subject field of the certificates matches the Fully Qualified Domain Name (FQDN) of the F5 host name registered in DNS. The certificate must also have a private key that corresponds to that certificate. Host names are case-sensitive and must match DNS and Active Directory records. Refer to the Microsoft article Obtain a Certificate and to the Genesys Security Deployment Guide.
  3. To enable key archival and recovery, set the following in the certificate template and on the CA:
    • The specific certificate template must be configured to allow key archival.
    • At least one key recovery agent must be identified on the CA, and a key recovery agent certificate must be issued to that agent.
    • Key archival must be configured on the CA.
  4. Import the F5 host certificate to each host running Configuration Proxy Servers, storing the certificate in the Personal Certificates folder of the Computer account. Refer to the Microsoft article Import a Certificate.
  5. On each Configuration Server Proxy, set the Listening Mode of the ports used for TLS communications to Auto-detect or Secure and attach the F5 host certificate. Refer to the Genesys Security Deployment Guide.

F5 Configuration

To ensure that replies from servers always traverse the load balancer on the way back to the client, SNAT (Secure Network Address Translation) is used. One of the most popular SNAT modes is the automap feature that allows mapping of all original client IP addresses to the self address of the F5 unit. The SNAT pool allows mapping of all the original client IP addresses to the IP addresses of the SNAT pool.

SNAT with a single IP address has a limit of 65535 ports. The SNAT connections might fail if a large number of client requests are traversing the SNAT. To mitigate port collisions, create SNAT pools or use SNAT automap with an appropriate number of self IP addresses on the Virtual LAN to support the expected level of concurrent connections using SNAT.

The following sample configuration is for a deployment where two IP addresses are used for the pool.

[+] Show sample configuration

Business Continuity

Genesys Workspace Desktop Edition integrates load-balanced Configuration Server Proxies into a Business Continuity solution, by keeping a pool of proxy servers at each Site (active and stand-by) of the configuration. In this case, a separate application and host object that represent the F5 load-balancer at each site must be created. Refer to Genesys Workspace Desktop Edition documentation for more information about how to set up Business Continuity for Agent Desktop when using Configuration Server Proxy objects from preferred and backup sites.

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 Server Proxy and 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 reconnection 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 tries to reconnect 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.
Retrieved from "https://docs.genesys.com/Documentation:FR:Dep:CSProxy:8.5.1 (2019-08-25 08:37:45)"
This page was last modified on April 7, 2017, at 11:15.


Comment on this article:

blog comments powered by Disqus