Pivotal GemFire Servers

A GemFire server is a Pivotal GemFire process that runs as a long-lived, configurable member of a distributed system.

The GemFire server is used primarily for hosting long-lived data regions and for running standard GemFire processes such as the server in a client/server configuration. You can start and stop cache servers using the following methods:
  • The easiest way to manage a GemFire The gfsh tool allows you to manage GemFire server processes from the command line.
  • You can also start, stop and manage the GemFire servers through the com.gemstone.gemfire.distributed.ServerLauncher API. The ServerLauncher API can only be used for GemFire Servers that were started with gfsh or with the ServerLauncher class itself. See the JavaDocs for additional specifics on using the ServerLauncher API.
Note: The ServerLauncher API cannot be used reliably for Servers started using the deprecated GemFire shell script, cacheserver.

You must have tools.jar (included with the JDK) added to your CLASSPATH in order to manage servers using either gfsh or the ServerLauncher API.

Server Configuration and Log Files

The gfsh server commands use a working directory for its configuration files and log files. These are the defaults and configuration options:
  • Cache servers are configured like any other GemFire process, with gemfire.properties and cache.xml files. It is not programmable except through application plug-ins. Typically, you provide the gemfire.properties file, the gfsecurity.properties file (if you are using a separate, restricted access security settings file) and the cache.xml file in the cache server’s working directory.
  • For logging output, log file output defaults to server_name.log in the cache server's working directory. If you restart a server with the same server name, the existing server_name.log file is automatically renamed for you (for example, server1-01-01.log or server1-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 server.
  • By default, the cache server will start in a subdirectory (named after the cache server) 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 cache server in gfsh.

Start the Cache Server

The startup syntax for cache servers in gfsh is:
start server --name=value [--assign-buckets(=value)?] 
[--cache-xml-file=value] [--classpath=value] [--disable-default-server(=value)?] 
[--enable-time-statistics(=value)?] [--force(=value)?] [--properties-file=value] 
[--group=value][--license-application-cache=value] [--license-data-management=value] 
[--locators=value] [--log-level=value] [--mcast-address=value] [--mcast-port=value] 
[--memcached-port=value] [--rebalance(=value)?] [--server-bind-address=value] 
[--server-port=value] [--statistic-archive-file=value] [--dir=value] 
[--initial-heap=value] [--max-heap=value] [--J=value(,value)*]
See start server for a detailed reference on all the parameters of the command.
Note: When both --max-heap and --initial-heap are specified during Server startup, additional GC parameters are specified internally by GemFire's Resource Manager. If you do not want the additional default GC properties set by the Resource Manager, then use the -Xms & -Xmx JVM options. See Control Heap Use with the Resource Manager for more information.
These following gfsh start server start sequences use a single XML file for cache configuration, specify different incoming client connection ports, and use a multicast port for peer discovery:
gfsh>start server --name=server1 --mcast-port=10338 \
--cache-xml-file=../serverConfig/cache.xml --server-port=40404

gfsh>start server --name=server2 --mcast-port=10338 --cache-xml-file=../serverConfig/cache.xml --server-port=40405
Here, the multicast port and cache.xml file specifications are in a gemfire.properties file:
#contents of D:\gfeserver\gemfire.properties 
#Tue May 09 17:53:54 PDT 2006 
mcast-port=10338 
cache-xml-file=D:\gfeserver\cacheCS.xml
To start the cache server using this gemfire.properties file, you can enter the following command:
gfsh>start server --name=server1 \
--properties-file=D:\gfeserver\gemfire.properties
To start a cache server with an embedded JMX Manager, you can enter the following command:
gfsh>start server --name=<server-name> --J=-Dgemfire.jmx-manager=true \
--J=-Dgemfire.jmx-manager-start=true

Check Server Status

If you are connected to the distributed system in gfsh, you can check the status of a running cache server by providing the server name. For example:
gfsh>status server --name=server1
If you are not connected to a distributed system, you can check the status of a local cache server by providing the process ID or the server's current working directory. For example:
gfsh>status server --pid=2484
or
gfsh>status server --dir=<server_working_directory>
where <server_working_directory> corresponds to the local working directory where the cache server is running.
If successful, the command returns the following information (with the JVM arguments that were provided at startup):
gfsh>status server --dir=server1
Server in C:\PivotalGemFire70\Latest\server1 on GemFireStymon[40404] as server1
is currently online.
Process ID: 2484
Uptime: 32 minutes 44 seconds
GemFire Version: 7.0
Java Version: 1.6.0_26
Log File: C:\PivotalGemFire70\Latest\server1\server1.log
JVM Arguments: 
...

Stop Server

If you are connected to the distributed system in gfsh, you can stop a running cache server by providing the server name. For example:
gfsh>stop server --name=server1
If you are not connected to a distributed system, you can stop a local cache server by specify the server's current working directory or the process ID. For example:
gfsh>stop server --pid=2484
or
gfsh>stop server --dir=<server_working_directory>
where <server_working_directory> corresponds to the local working directory where the cache server is running.

You can also use the gfsh shutdown command to shut down all cache servers in an orderly fashion. This is useful if you are using persistent regions. See Shutting Down the System for more details.

RHEL Only: Using the cacheserver Service

When you install Pivotal GemFire from RPM, the RPM also installs a cacheserver service. This allow you to manage a default cache server with the following commands:
/sbin/service cacheserver start
/sbin/service cacheserver stop
/sbin/service cacheserver restart
This cacheserver service obtains its default configuration from /etc/pivotal/gemfire/cacheserver.conf.
Inside the configuration file, the following default properties are defined:
  • Location of the cacheserver script:
    CACHESERVER_SCRIPT=/opt/pivotal/Pivotal_GemFire_702/bin/cacheserver
  • Current working directory for the server:
    CACHESERVER_WORK_DIR=/var/log/pivotal/gemfire/cacheserver 
  • Declarative cache configuration for the cache server:
    CACHE_XML_FILE=/opt/pivotal/gemfire/Pivotal_GemFire_702/defaultConfigs/cache.xml
  • Location of the gemfire.properties file for the cache server:
    JAVA_OPTS="-DgemfirePropertyFile=/opt/pivotal/gemfire/Pivotal_GemFire_702/defaultConfigs/gemfire.properties"
    
    You can modify this configuration to point your cacheserver service to a customized gemfire.properties file. In gemfire.properties, you can specify the name property, which will allow you to manage this cache server using the gfsh command-line utility.

Edit the cacheserver.conf file to configure the cacheserver service. You can also define your own additional cacheserver services. See /etc/sysconfig/cacheserver for instructions.