Running GemFire Locator Processes

This topic explains how to run a VMware Tanzu GemFire locator process.

The locator is a Tanzu 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 cluster.
Server locators give clients connection information to servers running in the locator’s cluster. 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 Tanzu 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 file lib/geode-dependencies.jar into the CLASSPATH of the JVM process. If you start a standalone locator using the LocatorLauncher API, you must specify this JAR file inside the command used to launch the locator process. For more information on CLASSPATH settings in Tanzu GemFire, see Setting Up the CLASSPATH. You can modify the CLASSPATH by specifying the --classpath parameter.
Locators are members of the cluster 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 cluster, 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 \
--locators='host1[9001],host2[9003]'
```
You can configure locators within the gemfire.properties file 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 gemfire.properties settings as other members of the cluster and the same gfsecurity.properties settings if you are using a separate, restricted access security settings file.

For example, to configure both locators and a multicast port in gemfire.properties:
```
locators=host1[9001],host2[9003]
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 cluster. When a locator is in the reconnecting state, it provides no discovery services for the cluster. 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 cluster. When you start servers using gfsh, the servers receive the group-level and cluster-level configurations from the locators.

See Overview 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 gfsh for more information on using gfsh. For example:
```
gfsh>start locator --name=locator1

gfsh> start locator --name=locator2 --bind-address=192.0.2.0 --port=13489
```
- Start the locator using the main method in the org.apache.geode.distributed.LocatorLauncher class and the Java executable. 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 (colocated) locator. Manage a colocated locator at member startup or through the APIs:

Use the gemfire.properties start-locator setting to start the locator automatically inside your Tanzu GemFire member. See the Reference. The locator stops automatically when the member exits. The property has the following syntax:
```
#gemfire.properties
start-locator=[address]port[,server={true|false},peer={true|false}]
```
Example:
```
#gemfire.properties
start-locator=13489
```

Use org.apache.geode.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 org.apache.geode.distributed.LocatorLauncher;

 public class MyEmbeddedLocator {

    public static void main(String[] args){
        LocatorLauncher locatorLauncher  = new LocatorLauncher.Builder()
          .setMemberName("locator1")
          .setPort(13489)
          .build();

          locatorLauncher.start();

          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) {
    validateArgs(args);

    locatorLauncher = new LocatorLauncher.Builder()
      .setMemberName(args[0])
      .setPort(Integer.parseInt(args[1])
      .setRedirectOutput(true)
      .build();
  }

  protected void args(final String[] args) {
    ...
  }

  public void run() {
    ...

    // start the Locator in-process
    locatorLauncher.start();

    // 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 "path/to/installation/lib/geode-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 cluster with 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 cluster, you can check the status of a local locator by providing the process ID, the Locator’s host name 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):

$ gfsh status locator --dir=locator1
Locator in /home/user/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..0_272
Log File: /home/user/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: /Users/username/apache_geode/lib/geode-dependencies.jar

Cluster configuration service is up and running.

Stop the Locator

If you are connected to the cluster with 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 cluster, 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.

Locators and Multi-Site (WAN) Deployments

If you use a multi-site (WAN) configuration, you can connect a locator to a remote site when starting the locator.

To connect a new locator process to a remote locator in a WAN configuration, specify the following at startup:

gfsh> start locator --name=locator1 --port=9009 --mcast-port=0 \
--J='-Dgemfire.remote-locators=192.0.2.0[9009],198.51.100.0[9009]'