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, there are two options:

Have a separate application server configuration file for each dispatcher.
1. Make a copy of the default configuration file (as.xcf) for each dispatcher, giving each copy a unique name.
2. Specify different settings for the ports and application data directory in each configuration file. The elements you need to configure are shown in Table 1.
3. Start each dispatcher with the -f option to specify the configuration file to use:
```
$FGLASDIR/bin/httpdispatch -f $FGLASDIR/etc/mydispatcherx.xcf
```
Alternatively, you can share the default configuration file between all the dispatchers by starting dispatchers with the -E option to specify unique ports and application data directories for each dispatcher. For more information and a sample command, go to Dispatcher override option (-E).

In addition, you will also need to configure your web server for multiple dispatchers:

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 different versions of Apache.
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. Configuration elements to define for each dispatcher
Elements	Resources	Setting values across dispatchers
`TCP_SERVER_PORT`	`res.ic.server.port`	A GAS dispatcher listening port is set by the `TCP_SERVER_PORT` element. Each dispatcher on a server requires a unique listening port. In fact, all port numbers – both the listening ports and the set admin ports – must be unique between all the dispatchers.
`TCP_ADMIN_PORT`	`res.ic.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 listening ports and the set admin ports – must be unique between all the dispatchers.
`res.appdata.path` (Application data directory)	`res.appdata.path`	The application data directory, or appdata, is where the application data files (log, tmp, session, and so on) managed by the GAS are located. It is recommended that this 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.

Dispatcher override option (-E)

You can share the default configuration file (as.xcf) between all the dispatchers provided you override the following resources with different values on starting the dispatcher:

res.ic.server.port
res.ic.admin.port
res.appdata.path

In this example, the dispatcher is started with the -E option to override the settings for the server port, admin port, and the appdata path. (Line breaks have been added to improve readability.)

$FGLASDIR/bin/httpdispatch -E res.ic.server.port=dispatcherx-server-port 
   -E res.ic.admin.port=dispatcherx-admin-port 
   -E res.appdata.path=appdatax-path

Where:

dispatcherx-server-port defines a unique listening port for this dispatcher.
dispatcherx-admin-port defines the unique admin port for this dispatcher.
appdatax-path defines the unique path to the appdata directory for this dispatcher.

Shared application data directory

Sharing the same application data directory (appdata) 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 for each dispatcher, it is important to ensure that the log, tmp, and session directories located under the appdata directory remain independent and unique between all the dispatchers.

You have two options:

Set these resources directly in the application server configuration file (a copy of the default as.xcf) for each dispatcher. For an example, go to Table 2.
Alternatively, you can start dispatchers with the -E option to override these resources. For an example, go to Dispatcher override option (-E) example

Table 2. Configure different log, tmp, and session directories per dispatcher
Elements	Resources	Configuration file (as1.xcf) examples
`OUTPUT`	`res.log.output.path`	`<RESOURCE Id="res.log.output.path" Source="INTERNAL">$(res.appdata.path)/dispatcherx-log</RESOURCE>`
`TEMPORARY_DIRECTORY`	`res.path.tmp`	`<RESOURCE Id="res.path.tmp" Source="INTERNAL">$(res.appdata.path)/dispatcherx-tmp</RESOURCE>`
`SESSION_DIRECTORY`	`res.path.session`	`<RESOURCE Id="res.path.session" Source="INTERNAL">$(res.appdata.path)/dispatcherx-session</RESOURCE>`

Dispatcher override option (-E) example

You can share the appdata path (shown in Default as.xcf appdata settings) between all the dispatchers provided you override the following resources with different values on starting the dispatcher:

res.log.output.path
res.path.tmp
res.path.session

In this example, the dispatcher is started with the -E option to override the settings for log, tmp, and session directories of the appdata path. (Line breaks have been added to improve readability.)

$FGLASDIR/bin/httpdispatch -E res.log.output.path=/work/gas/appdata/dispatcherx-log 
   -E res.path.tmp=/work/gas/appdata/dispatcherx-tmp 
   -E res.path.session=/work/gas/appdata/dispatcherx-session

Where:

/dispatcherx-log defines a unique directory for the logs for this dispatcher.
/dispatcherx-tmp defines a unique temp directory for this dispatcher.
/dispatcherx-session defines a unique session directory for this dispatcher.

Default as.xcf appdata settings

In this example, the default settings for the appdata resources of the GAS are shown. The res.appdata.path resource specifies the appdata directory, which is the root directory for the log, tmp, and session directories. In the example, the appdata path is shown for a Windows® system.

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

Resources for the log, tmp, and session directories are set within the appdata directory:

The res.log.output.path resource and the LOG element define the path to the log directory:

<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 and the TEMPORARY_DIRECTORY element define the path to the temporary directory:

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

The res.path.session resource and the SESSION_DIRECTORY element define the path to the session directory:

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