Configuring the gfsh Environment

The gfsh.bat and gfsh bash script automatically append the required GemFire and JDK .jar libraries to your existing CLASSPATH. There are user-configurable properties you can set for security, environment variables, logging, and troubleshooting.

JAR Libraries in CLASSPATH

The .jar libraries that need to be in your CLASSPATH to run gfsh commands include:
  • gemfire.jar
  • antlr.jar
  • gfsh-dependencies.jar
  • tomcat-embed-core.jar
  • tomcat-embed-logging-juli.jar
  • tomcat-embed-jasper.jar
  • ecj-3.7.2.jar
  • spring-asm-3.1.1.RELEASE.jar

These JAR files are packaged in your GemFire installation in the $GEMFIRE/lib (or on Windows, the %GEMFIRE%\lib) directory.

The gfsh command-line utility also requires that the tools.jar included with JDK is added to your CLASSPATH. The gfsh scripts add $JAVA_HOME/lib/tools.jar or %JAVA_HOME%\lib\tools.jar to your CLASSPATH.

Note: If you wish to start a GemFire Pulse application server from the gfsh interface, you must also add $GEMFIRE/lib/commons-logging.jar to your CLASSPATH. The tomcat-* JAR files listed above (also used by GemFire Pulse) are automatically added for you by the gfsh scripts, however commons-logging.jar must be added manually.

Machine Hostname

On some operating systems, you may need to ensure that the hostname of your machine is configured in your system hosts file. For example, on MacOS you may need to map your machine's hostname to your IP address in the /etc/hosts file in order for gfsh and Pulse to operate correctly.

Configuring gfsh Security

Since gfsh must connect to a JMX Manager member to run certain commands (namely those commands that manage and monitor other members), JMX Manager configuration properties can affect gfsh security. In gemfire.properties, the following GemFire properties can affect gfsh connection settings to the JMX Manager:
  • jmx-manager-ssl
  • jmx-manager-port
  • jmx-manager-password-file
  • jmx-manager-access-file

You may also need to verify that the ports are available and open to client connections. See Configuring a JMX Manager for details on these security properties.

Configuring gfsh Environment Variables

In addition, you can set several gfsh-specific preset SHELL variables by using the set variable command. For example, you can set gfsh to run in quiet mode. Not all gfsh variables are modifiable; user-configurable variables include:
  • APP_FETCH_SIZE
  • APP_COLLECTION_LIMIT
  • APP_QUIET_EXECUTION
See Useful gfsh Shell Variables for more information.

gfsh Logging and Troubleshooting

gfsh writes several log files while running. Useful log files include:
  • gfsh-YYYY-MM-DD_HH-MM-SS.log. Records the events of an individual gfsh session. It includes environment information, such as Java and system information, and detailed command execution. The log file is written to the current working directory where you have executed the gfsh or gfsh.bat script. The desired log level for this file can be set using gfsh.log-level system property. Add it to the JAVA_ARGS environment before starting gfsh. You cannot modify the output filename or the location where the log file is written.
  • <locator-name>.log. Details a locator's configuration (including all gemfire.properties) and all activity that occurs on the locator after startup. This log file is written to a directory that is named after the locator. For example, if you start a locator named locator1, the file is written as locator1.log in the <product_dir>/locator1 directory.
  • vf.gf.locator.pid. Contains the process ID of the locator. You can use the PID to stop or view the status of this locator. This file is written to the same directory location as the locator's log file .
  • <server-name>.log. Details a server's configuration (including all gemfire.properties) and all activity that occurs on the server after startup. This log file is written to a directory that is named after the server. For example, if you start a server named server1, the file is written as server1.log in the <product_dir>/server1 directory. If you stop and start the server with an identical name, the older log files are kept in the same directory but renamed for versioning purposes.
  • vf.gf.server.pid. Contains the process ID of the server. You can use the PID to stop or view the status of this server. This file is written to the same location as the server log file.

In addition, gfsh records a history of commands in the gfsh.history file, which you can use to create scripts or review past commands.

Command History and gfsh.history

A history of commands that have been executed successfully is logged in .gfsh.history file in the home directory of the user running gfsh. You can also export a history file by using the history --file=your_file_name command.

JMX Manager Update Rate and System Monitoring

When you perform data operations (such as put) and then monitor the state of the system (such as using the gfsh show metrics command or GemFire Pulse), the monitored system may not immediately reflect the most recent operations. For example, if you perform a put operation and then immediately execute the show metrics gfsh command, you may not see the correct number of entries in the region. The management layer updates every 2 seconds. Wait a few seconds after performing operational activity to see the most accurate results.

You can modify the jmx-manager-update-rate property in gemfire.properties to increase or decrease the rate (specified in milliseconds) at which updates are pushed to the JMX Manager. This property setting should be greater than or equal to the statistic-sample-rate. You may want to increase this rate if you are experiencing performance issues; however, setting this value too high will cause stale values to be seen in gfsh and GemFire Pulse.