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 will have its own uniquely-named configuration file, and each configuration file must take into account the settings for the elements shown in Table 1.

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`	No independent resource available; the path can only be set directly in the configuration file.	`<SESSION_DIRECTORY>$(res.appdata.path)/dispatcher1-session</SESSION_DIRECTORY>`	Not applicable

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\3.21</RESOURCE>

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

<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/$(dispatcher.name)</RESOURCE>

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

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