The gfsh.bat and gfsh bash script automatically append the required VMware Tanzu 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
When you start up gfsh, it will automatically load required JAR files that have been packaged in the gfsh-dependencies.jar file. You do not need to modify your CLASSPATH to run gfsh.
The JAR files are packaged within your installation directory in the lib directory.
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 Tanzu GemFire properties can affect gfsh connection settings to the JMX Manager:
jmx-manager-ssljmx-manager-portjmx-manager-password-filejmx-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 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_QUIET_EXECUTION
See Useful gfsh Shell Variables for more information.
Configuring gfsh Session Logging
By default, gfsh session logging is deactivated. To enable gfsh logging, you must set the Java system property -Dgfsh.log-level=desired_log_level where desired_log _level is one of the following values: severe, warning, info, config, fine, finer, finest. For example, in Linux:
export JAVA_ARGS=-Dgfsh.log-level=info
Then, start gfsh.
gfsh produces a log file named gfsh-%u_%g.log. This log file records the events of an individual gfsh session. It includes environment information, such as Java and system information, and detailed command execution. The variables are replaced as follows:
- %u - a unique number to resolve conflicts
- %g - the generation number to distinguish rotated logs
gfsh uses the JDK Logger to generate gfsh session log files. See http://docs.oracle.com/javase/7/docs/api/java/util/logging/FileHandler.html for a description of how the variables are used in naming the log file. The default name of the generated gfsh log file cannot be changed.
By default, the log file is written to the current working directory where you have executed the gfsh or gfsh.bat script. To modify the directory location where log files are written, use the gfsh.log-dir Java system property. For example:
export JAVA_ARGS="-Dgfsh.log-level=info -Dgfsh.log-dir=/machinename/logs"
Then, start gfsh.
In addition, gfsh records a history of commands in the ${SYS_USER_HOME}/.geode/.gfsh.history file, which you can use to create scripts or review past commands.
Member Log Files
gfsh writes several log files for any members that are started via gfsh. Useful member log files include:
- <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.login the<product_dir>/locator1directory. - 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.login the<product_dir>/server1directory. 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.
Viewing Standard Output and Standard Error
By default, Tanzu GemFire does not show messages written by the application to standard output and standard error. To allow these messages to be written to the locator and server log files, respectively, specify the --redirect-output option with the gfsh start locator or start server commands. For example, the following command causes stdout and stderr messages to be written to the locator1.log file:
gfsh> start locator --name=locator1 --redirect-output
Tab Completion
This section applies only to UNIX installations.
When you run gfsh commands from a UNIX bash shell, you can enable automatic tab-completion in the shell by running the following command:
source <gemfire-install-directory>/bin/gfsh-completion.bash
After running this command, you can use auto completion when running gfsh commands from the bash shell.
See Using Tab Completion.
Command History and gfsh.history
A history of commands that have been executed successfully is logged in .gfsh.history file in a .gemfire directory under 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 Tanzu 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 Tanzu GemFire Pulse.
Formatting of Results
This section applies only to UNIX installations.
gfsh commands such as query produce output with wide columns that may become misaligned and require manual reformatting to view the output. If the output cannot fit in the available width of the terminal, gfsh automatically trims the columns widths to fit. You can deactivate this behavior by setting the gfsh environment variable APP_RESULT_VIEWER to an arbitrary value that is not external or basic.
You can set the APP_RESULT_VIEWER variable to external to enable viewing of the output using the UNIX less command.
