Pivotal GemFire® v8.1

Pivotal GemFire Locator Processes

Pivotal GemFire Locator Processes

The locator is a Pivotal GemFire process that tells new, connecting members where running members are located and provides load balancing for server use.

You can run locators as peer locators, server locators, or both:

  • Peer locators give joining members connection information to members already running in the locator's distributed system.
  • Server locators give clients connection information to servers running in the locator's distributed system. Server locators also monitor server load and send clients to the least-loaded servers.

By default, locators run as peer and server locators.

You can run the locator standalone or embedded within another GemFire process. Running your locators standalone provides the highest reliability and availability of the locator service as a whole.

Locator Configuration and Log Files

Locator configuration and log files have the following properties:

  • When you start a standalone locator using gfsh, gfsh will automatically load the required JAR files ($GEMFIRE/lib/locator-dependencies.jar into the CLASSPATH of the JVM process. If you start a standalone locator using the LocatorLauncher API, you must specify $GEMFIRE/lib/locator-dependencies.jar inside the command used to launch the locator process. For more information on CLASSPATH settings in GemFire, see CLASSPATH Settings for GemFire Processes. You can modify the CLASSPATH by specifying the --classpath or parameter
  • Locators are members of the distributed system just like any other member. In terms of mcast-port and locators configuration, a locator should be configured in the same manner as a server. Therefore, if there are two other locators in the distributed system, each locator should reference the other locators (just like a server member would). For example:
    gfsh> start locator --name=locator1 --port=9009 --mcast-port=0 \
  • You can configure locators by using or by specifying start-up parameters on the command line. If you are specifying the locator's configuration in a properties file, locators require the same settings as other members of the distributed system and the same settings if you are using a separate, restricted access security settings file.
    For example, to configure both locators and a multicast port in
  • If you need to configure a locator to connect to a remote site in a multi-site (WAN) configuration, you can specify the following:
    gfsh> start locator --name=locator1 --port=9009 --mcast-port=0 \
  • There is no cache configuration specific to locators.
  • For logging output, the locator creates a log file in its current working directory. Log file output defaults to locator_name.log in the locator's working directory. If you restart a locator with a previously used locator name, the existing locator_name.log file is automatically renamed for you (for example, locator1-01-01.log or locator1-02-01.log). You can modify the level of logging details in this file by specifying a level in the --log-level argument when starting up the locator.
  • By default, a locator will start in a subdirectory (named after the locator) under the directory where gfsh is executed. This subdirectory is considered the current working directory. You can also specify a different working directory when starting the locator in gfsh.
  • By default, a locator that has been shutdown and disconnected due to a network partition event or member unresponsiveness will restart itself and automatically try to reconnect to the existing distributed system. When a locator is in the reconnecting state, it provides no discovery services for the distributed system. See Handling Forced Cache Disconnection Using Autoreconnect for more details.

Locators and the Cluster Configuration Service

Locators use the Cluster Configuration Service to save configurations that apply to all cluster members, or to members of a specified group. The configurations are saved in the Locator's directory and are propagated to all locators in a distributed system. When you start servers using gfsh, the servers receive the group-level and cluster-level configurations from the locators.

SeeOverview of the Cluster Configuration Service.

Start the Locator

Use the following guidelines to start the locator:

  • Standalone locator. Start a standalone locator in one of these ways:
    • Use the gfsh command-line utility. See Using the Pivotal GemFire SHell (gfsh) for more information on using gfsh. The syntax for starting the

      Example commands:

      gfsh>start locator --name=locator1
      gfsh> start locator --name=locator2 --bind-address= --port=13489
      Note: If you are using gfsh on Windows, specify the gemfire.OSProcess.ENABLE_OUTPUT_REDIRECTION=true parameter when starting up locators. This parameter allows you to avoid an issue where gfsh hangs when starting processes on Windows platforms. For example:
      gfsh>start locator --name=locator1 --dir=. --J=-Dgemfire.OSProcess.ENABLE_OUTPUT_REDIRECTION=true
    • Start the locator using the main method in the com.gemstone.gemfire.distributed.LocatorLauncher class and the Java executable. For example:
      working/directory/of/Locator/process$java -server -classpath "$GEMFIRE/lib/locator-dependencies.jar:/path/to/application/classes.jar" \
       com.gemstone.gemfire.distributed.LocatorLauncher start Locator1 --port=11235 --redirect-output

      Specifically, you use the LocatorLauncher class API to run an embedded Locator service in Java application processes that you have created. The directory where you execute the java command becomes the working directory for the locator process.

    • When starting up multiple locators, do not start them up in parallel (in other words, simultaneously). As a best practice, you should wait approximately 30 seconds for the first locator to complete startup before starting any other locators. To check the successful startup of a locator, check for locator log files. To view the uptime of a running locator, you can use the gfsh status locator command.
  • Embedded (co-located) locator. Manage a co-located locator at member startup or through the APIs:
    • Use the start-locator setting to start the locator automatically inside your GemFire member. See and (GemFire Properties). The locator stops automatically when the member exits. The property has the following syntax:

    • Use com.gemstone.gemfire.distributed.LocatorLauncher API to start the locator inside your code. Use the LocatorLauncher.Builder class to construct an instance of the LocatorLauncher, and then use the start() method to start a Locator service embedded in your Java application process. The other methods in the LocatorLauncher class provide status information about the locator and allow you to stop the locator.
      import com.gemstone.gemfire.distributed.LocatorLauncher;
       public class MyEmbeddedLocator {
          public static void main(String[] args){
              LocatorLauncher locatorLauncher  = new LocatorLauncher.Builder()
                System.out.println("Locator successfully started");
      Here's another example that embeds the locator within an application, starts it and then checks the status of the locator before allowing other members to access it:
      package example;
      import ...
      class MyApplication implements Runnable {
        private final LocatorLauncher locatorLauncher;
        public MyApplication(final String... args) {
          locatorLauncher = new LocatorLauncher.Builder()
        protected void args(final String[] args) {
        public void run() {
          // start the GemFire Locator in-process
          // wait for Locator to start and be ready to accept member (client) connections
          locatorLauncher.waitOnStatusResponse(30, 5, TimeUnit.SECONDS);
        public static void main(final String... args) {
          new MyApplication(args).run();
      Then to execute the application, you would run:
      /working/directory/of/MyApplication$ java -server -classpath "$GEMFIRE/lib/locator-dependencies.jar:/path/to/application/classes.jar" example.MyApplication Locator1 11235
      The directory where you execute the java command becomes the working directory for the locator process.

Check Locator Status

If you are connected to the distributed system in gfsh, you can check the status of a running Locator by providing the Locator name. For example:
gfsh>status locator --name=locator1
If you are not connected to a distributed system, you can check the status of a local Locator by providing the process ID, the Locator's hostname and port, or the Locator's current working directory. For example:
gfsh>status locator --pid=2986
gfsh>status locator --host=host1 --port=1035
$ gfsh status locator --dir=<locator_working_directory>
where <locator_working_directory> corresponds to the local working directory where the locator is running.
If successful, the command returns the following information (with the JVM arguments that were provided at startup):
stymon@ubuntu:~$ gfsh status locator --dir=locator1
Locator in /home/stymon/locator1 on ubuntu.local[10334] as locator1 is currently online.
Process ID: 2359
Uptime: 17 minutes 3 seconds
GemFire Version: 8.0.0
Java Version: 1.7.0_65
Log File: /home/stymon/locator1/locator1.log
JVM Arguments: -Dgemfire.enable-cluster-configuration=true -Dgemfire.load-cluster-configuration-from-dir=false
 -Dgemfire.launcher.registerSignalHandlers=true -Djava.awt.headless=true -Dsun.rmi.dgc.server.gcInterval=9223372036854775806
Class-Path: /home/stymon/Pivotal_GemFire_800_b48319_Linux/lib/locator-dependencies.jar:/usr/local/java/lib/tools.jar

Cluster configuration service is up and running.

Stop the Locator

If you are connected to the distributed system in gfsh, you can stop a running locator by providing the locator name. For example:
gfsh>stop locator --name=locator1
If you are not connected to a distributed system, you can stop a local locator by specifying the locator's process ID or the locator's current working directory. For example:
gfsh>stop locator --pid=2986
gfsh>stop locator --dir=<locator_working_directory>
where <locator_working_directory> corresponds to the local working directory where the locator is running.