This page describes an older version of the product. The latest stable version is 16.4.

The Runtime Environment

A processing unit is deployed onto the XAP runtime environment, which is called the Service Grid. It is responsible for materializing the processing unit’s configuration, provisioning its instances to the runtime infrastructure and making sure they continue to run properly over time.

Starting a Service Grid

In order to start the GSA, the <XAPHOME>/bin/gs-agent.(sh/bat) can be used.

The preferable (and easiest) way to start a Service Grid is the Grid Service Agent. However, each of the components can be started manually.

The following table summarized how to start each component:

Component Linux (XAP) Windows (XAP) Windows (XAP.NET)
GSA gs-agent.bat gs-agent.exe
GSC gsc.bat gsc.exe
GSM gsm_nolus.bat N\A
LUS startJiniLUS.bat lus.exe
GSM + LUS gsm.bat gsm.exe

GSA Parameters

The GSA parameters control how many local process the GSA will spawn on startup (per process type), and the number of globally managed process the GSA will maintain (in cooperation with other GSAs) (per process type). By default, the GSA is started with 2 local Grid Service Containers, and manage 2 global Grid Service Manager and 2 global Lookup Service. This is the equivalent of starting the GSA with the following parameters:

gs-agent gsa.gsc 2 2 2

In order to, for example, start 3 local GSCs, 2 global GSMs, and no global LUS, the following command can be used:

gs-agent gsa.gsc 3 2 0

In general, the gsa.[process type] followed by a number controls the number of local processes of the specific process type that will be spawned by the GSA. The[process type] following by a number controls the number of globally managed processes of the specific process type.

Lookup Service Considerations

When starting a Lookup Service and other services in unicast mode (not multicast), it means that specific machines will be the ones that will run the Lookup Service. This means that on the machines running the LUS, the following command will be used (assuming other defaults are used for GSM and GSC):

gs-agent 0 gsa.lus 1

And on machines that will not run the LUS, the following command should be used:

gs-agent 0

You can use the GigaSpaces Universal Deployer to deploy complex multi processing unit applications.

Customizing GSA Components

GSA manages different process types. Each process type is defined within the <XAPHOME>\config\gsa directory in an xml file that identifies the process type by its name.


You can change the default location of the GSA configuration files using the com.gigaspaces.grid.gsa.config-directory system property.

The following are the process types that come out of the box:

Processes Type Description XML config file name Properties file name
gsc Defines a Grid Service Container gsc.xml
gsm Defines a Grid Service Manager gsm.xml
lus Defines a Lookup Service lus.xml
gsm_lus Defines a Grid Service Manager and Lookup Service within the same JVM gsm_lus.xml
esm Defines an Elastic Service Manager which is required for deploying Elastic Processing Unit esm.xml

Here is an example of the gsc xml configuration file:

<process initial-instances="script" shutdown-class="com.gigaspaces.grid.gsa.GigaSpacesShutdownProcessHandler" restart-on-exit="always">
 <script enable="true" work-dir="${}/bin"
 <vm enable="true" work-dir="${}/bin"

The GSA can either spawn a script based process, or a pure JVM (with its arguments) process. The GSC for example, allows for both types of process spawning.

  • The initial-instances parameter controls what type of spawning will be performed when the GSA spawns processes by itself (and not on demand by the Admin API).
  • The shutdown-class followed by the restart-on-exit flag, controls if the process will be restarted upon termination. There are three types of values:
    • restart-on-exit=“always”: Always restarts the process if it exits
    • restart-on-exit=“never”: Never restarts the process if it exists
    • restart-on-exit=“!0”: Restarts the process only if the exit code is different than 0
  • The shutdown-class is an implementation of com.gigaspaces.grid.gsa.ShutdownProcessHandler interface and provides the default shutdown hooks before and after shutdown of a process, to make sure it is shutdown properly. The shutdown-class can be omitted.
  • The restart-regex (there can be more than one element) is applied to each console output line of the managed process, and if there is a match, the GSA will automatically restart the process. By default, the GSC will be restarted if there is an OutOfMemoryError.

Grid Configuration

Service Grid configuration is often composed of two layers: system-wide configuration and component-specific configuration. The system-wide configuration specifies settings which all components share, e.g. discovery (unicast/multicast), security, zones, etc. These are set in the EXT_JAVA_OPTIONS environment variable. The component-specific configuration specifies settings per component type, e.g. the GSC memory limit is greater than the GSM and LUS. These are set in one or more of the following environment variables:


For example:

export GSA_JAVA_OPTIONS=-Xmx256m
export GSC_JAVA_OPTIONS=-Xmx2048m
export GSM_JAVA_OPTIONS=-Xmx1024m
export LUS_JAVA_OPTIONS=-Xmx1024m

. ./
set GSC_JAVA_OPTIONS=-Xmx2048m
set GSM_JAVA_OPTIONS=-Xmx1024m
set LUS_JAVA_OPTIONS=-Xmx1024m

call gs-agent.bat

Configuring independent components

It is highly recommended that the Service Grid is started (and configured) using the gs-agent as shown above. If you do need to start a specific component separately, you can use the same environment variables shown above.

For example:

export GSC_JAVA_OPTIONS=-Xmx1024m

. ./
set GSC_JAVA_OPTIONS=-Xmx1024m

call gsc.bat

Component specific configuration can be set using system properties (follows the [component name].[property name] notation).