Running GemFire Locator Processes
Running 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 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.
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.
- Use the gfsh
command-line utility. See gfsh (GemFire SHell) for more information on
using gfsh. The syntax for starting the
-
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.
- 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:
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=2986or
gfsh>status locator --host=host1 --port=1035or
$ gfsh status locator --dir=<locator_working_directory>where <locator_working_directory> corresponds to the local working directory where the locator is running.
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=2986or
gfsh>stop locator --dir=<locator_working_directory>where <locator_working_directory> corresponds to the local working directory where the locator is running.