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 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 \
  --locators='host1[9001],host2[9003]'

• You can configure locators by using gemfire.properties 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 distributed system 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 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 gfsh (GemFire SHell) 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=192.168.129.205 --port=13489
    

  • 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 gemfire.properties start-locator setting to start the locator automatically inside your GemFire member. See gemfire.properties and gfsecurity.properties (GemFire Properties). 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 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()
              .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 "$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.

Locators and Multi-Site (WAN) Deployments

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

Check Locator Status

gfsh>status locator --name=locator1

gfsh>status locator --pid=2986

gfsh>status locator --host=host1 --port=1035

$ gfsh status locator --dir=<locator_working_directory>

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

gfsh>stop locator --name=locator1

gfsh>stop locator --pid=2986

gfsh>stop locator --dir=<locator_working_directory>