Running VMware Tanzu GemFire Locator Processes

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

A Tanzu GemFire locator is a 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 both peer and server locators.

Start a Locator with gfsh

This example uses the gfsh start locator command to start a default locator named “locator1”:

gfsh>start locator --name=locator1

When starting multiple locators, use parameters to give each a unique name, bind-address, and port to avoid conflicts with other locators. For example, this command starts “locator2” with a unique address and port:

gfsh> start locator --name=locator2 --bind-address=192.0.2.0 --port=13489

See the gfsh start locator reference page for command syntax.

Do not start locators 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.

Locator Configuration and Log Files

Locator configuration and log files have the following properties:

Locators are members of the cluster just like any other member. 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 \
--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 locators in gemfire.properties:
```
locators=host1[9001],host2[9003]
```
There is no cache configuration specific to locators.
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 log file is automatically renamed, for example, locator1-01-01.log becomes locator1-02-01.log). You can modify the level of logging details in this file by specifying the desired level with the --log-level parameter.
By default, the locator starts in a subdirectory, named after the locator, under the current working directory of the gfsh process. This subdirectory is considered the locator’s current working directory. You can also specify a different working directory with the --dir parameter.
By default, a locator that has been shut down and disconnected due to a network partition event or member unresponsiveness restarts and tries 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 Auto-reconnect 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. See Overview of the Cluster Configuration Service. Servers receive the group-level and cluster-level configurations from the locators.

Check Locator Status

Once connected to the cluster with gfsh, check the status of a running locator by providing the locator name:

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.

The command returns the following information, with the JVM arguments that were provided at startup:

$ gfsh status locator --dir=locator1
Locator in /Users/workspace/locator1 on 192.168.129.113[10334] as locator1 is currently online.
Process ID: 46075
Uptime: 55 seconds
VMware GemFire Version: 10.0.0
Java Version: 11.0.17
Log File: /Users/workspace/locator1/locator1.log
JVM Arguments:
...

Stop the Locator

When connected to the cluster in gfsh, stop a running locator by providing the locator name:

gfsh>stop locator --name=locator1

If not connected, 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 addresses of remote locators at startup:

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

Start a Locator Programmatically

Running your locators standalone, as described above, provides the highest reliability and availability of the locator service as a whole. But in some situations, you may choose to run an embedded locator.

To start the locator inside your code, use the org.apache.geode.distributed.LocatorLauncher API. Use the LocatorLauncher.Builder class to construct an instance of the LocatorLauncher, and then use the start() method to start the locator service. 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 ExampleLocatorApplication {
  public static void main(final String[] args) {
    final LocatorLauncher locatorLauncher = new LocatorLauncher.Builder()
      .setMemberName("locator1")
      .setPort(13489).build();

    locatorLauncher.start();

    System.out.println("Locator successfully started");
    System.out.println(args[0]);
  }
}

This example demonstrates how to start a GemFire locator embedded in your own Java application via the LocatorLauncher utilizing the GemFire Bootstrap. Using the GemFire Bootstrap is necessary to load GemFire Extensions, like GemFire Search, and isolate GemFire from other loaded application classes. When using the GemFire Bootstrap, you must be sure to define a GEMFIRE_HOME environment variable or a gemfire.home system property that points to the VMware GemFire top-level installation directory.

The class com.examples.ExampleLocatorApplication has a static void main(String[]) method, like any other Java application. It uses the org.apache.geode.distributed.LocatorLauncher to embed a GemFire locator in the Java application.

The Java application is executed through GemFire Bootstrap’s com.vmware.gemfire.bootstrap.Main Java application class. The command includes only the GemFire Bootstrap jar in the Java classpath. Your application classes and jars can be added via the --automatic-module-classpath argument. You should not include any other jars in the Java classpath directly.

$ java -classpath gemfire-bootstrap.jar com.vmware.gemfire.bootstrap.Main \
    com.examples.ExampleLocatorApplication \
    --automatic-module-classpath <classes:jar:...> \
    [application arguments ...]