Configure multiple dispatchers

If you have multiple dispatchers on a host, you must specify unique ports and application data directories for each dispatcher to ensure dispatcher information does not get mixed up.

While multiple dispatchers are typically not needed, you might have multiple dispatchers to support different environments using the same version of the Genero Application Server on the same host. For example, you may wish to co-locate your production, training, and development environments.

To start multiple dispatchers on a single host:
  • Create a copy of the application server configuration file (default as.xcf) for each dispatcher. Each dispatcher must have its own uniquely-named configuration file.
  • Specify different settings for the elements shown in Table 1 in each configuration file.
  • If using Apache web server, you must create different ProxyPass and ProxyPassReverse directives in the Apache configuration for each fastcgidispatch dispatcher, as Apache must deliver requests to the GAS with the corresponding port and path alias. For more information on configuring Apache, go to FastCGI GAS configuration on various web server.
  • If using Internet Information Services (IIS) web server, you must create a different application pool for each isapidispatch dispatcher, each with its own application root directory containing the isapidispatch.ini file. For more information on configuring IIS, go to Manual configuration for IIS 8.x and IIS 10.x.
Table 1. Elements defined for each dispatcher
Element(s) Setting values across dispatchers
TCP_BASE_PORT + TCP_PORT_OFFSET A GAS dispatcher listening port is set by adding the port offset to the base port. Each dispatcher on a server requires a unique listening port. In fact, all port numbers – both the computed listening ports and the set admin ports – must be unique between all the dispatchers.
Tip:

Giving a different TCP_BASE_PORT for each dispatcher will make dispatchers more recognisable to you from the address line of the apps they are running.
TCP_ADMIN_PORT The admin port is for GAS administration tasks. Each dispatcher on a server requires a unique admin port. In fact, all port numbers – both the computed listening ports and the set admin ports – must be unique between all the dispatchers.
res.appdata.path (Application data directory) The application data directory is the directory for GAS data files. It is recommended that the directory be unique between all the dispatchers.
Tip:

While not recommended, you can share the application data directory between dispatchers. For more information, see Shared application data directory.
SOCKET_PATH (socket path directory) A unique socket path is needed for each dispatcher. By default, SOCKET_PATH is configured as /tmp for Linux®/UNIX™ systems. It is mandatory to set a unique path in the SOCKET_PATH element for each dispatcher in your multiple dispatcher configuration environment.
Important: Socket path length

UNIX socket path length is system dependent and cannot exceed a specific limit.

Dispatcher override option (-E)

You can share the same configuration file between all the dispatchers provided you run the dispatcher with the -E option to override the resources shown in Table 2 for each instance with different values.
Table 2. Override resources
Element (s) Resource Override example
TCP_BASE_PORT res.ic.base.port httpdispatch -E res.ic.base.port=dispatcher1-base-port
TCP_PORT_OFFSET res.ic.port.offset httpdispatch -E res.ic.port.offset=myOffset
TCP_ADMIN_PORT res.ic.admin.port httpdispatch -E res.ic.admin.port=dispatcher1-admin-port
res.appdata.path (Application data directory) res.appdata.path httpdispatch -E res.appdata.path=/work/tmp/gas/appdata1
SOCKET_PATH (socket path directory) res.dispatcher.socket.path httpdispatch -E res.dispatcher.socket.path=/tmp1

Shared application data directory

Sharing the same application data directory between all the dispatchers is not recommended. For more information on why you need to be cautious about this, see Why do my applications fail using multiple dispatchers? and Error taking session ownership.

However, if you want to use the same application data directory, specified by the resource res.appdata.path, for each dispatcher, it is important to ensure that directories located under the directory remain independent.

The log, tmp, and session directories need to be unique between all the dispatchers. You can change these directly in the application server configuration file (a copy of the default as.xcf) for each dispatcher, or run the dispatcher with the -E option to override the resource. For examples, see Table 3.

Table 3. Configure different appdata log, tmp, and session directories per dispatcher
Element (s) Resource Configuration file (as1.xcf) example Override example
OUTPUT res.log.output.path <RESOURCE Id="res.log.output.path" Source="INTERNAL">$(res.appdata.path)/dispatcher1-log</RESOURCE> httpdispatch -E res.log.output.path=/work/gas/appdata/dispatcher1-log
TEMPORARY_DIRECTORY res.path.tmp <RESOURCE Id="res.path.tmp" Source="INTERNAL">$(res.appdata.path)/dispatcher1-tmp</RESOURCE> httpdispatch -E res.path.tmp=/work/gas/appdata/dispatcher1-tmp
SESSION_DIRECTORY res.path.session <RESOURCE Id="res.path.session" Source="INTERNAL">$(res.appdata.path)/dispatcher1-session</RESOURCE> httpdispatch -E res.path.session=/work/gas/appdata/dispatcher1-session
These examples are extracted from the default application server configuration file, as.xcf:
-- The res.appdata.path resource specifies the directory for application data
-- for the dispatcher

<RESOURCE Id="res.appdata.path"
 Source="INTERNAL">C:\ProgramData\FourJs\gas\4.01</RESOURCE>

-- The res.log.output.path resource specifies the log directory
-- as defined by the LOG element

<RESOURCE Id="res.log.output.path"
 Source="INTERNAL">$(res.appdata.path)/log</RESOURCE>
<LOG>
  <OUTPUT Type="$(res.log.output.type)">$(res.log.output.path)</OUTPUT>
  ...
</LOG>

-- The res.path.tmp resource specifies the temporary directory
-- as defined by the TEMPORARY_DIRECTORY element

<RESOURCE Id="res.path.tmp"
 Source="INTERNAL">$(res.appdata.path)/tmp</RESOURCE>

<TEMPORARY_DIRECTORY>$(res.path.tmp)</TEMPORARY_DIRECTORY>

-- The res.path.session resource specifies the session directory
-- as defined by the SESSION_DIRECTORY element

<RESOURCE Id="res.path.session"
 Source="INTERNAL">$(res.appdata.path)/session</RESOURCE>

<SESSION_DIRECTORY>$(res.path.session)</SESSION_DIRECTORY>