---
title:  Configuring the gfsh Environment
---

<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements.  See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

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


## <a id="concept_3B9C6CE2F64841E98C33D9F6441DF487__section_0D2EEA7A9ED54DFDB2E1EE955E47921E" class="no-quick-link"></a>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.

## <a id="concept_3B9C6CE2F64841E98C33D9F6441DF487__section_02EEF9A519094EAD9D6B5C8E896EBA27" class="no-quick-link"></a>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.

## <a id="concept_3B9C6CE2F64841E98C33D9F6441DF487__section_3FA4CD2B451B4A30A12D30DDE8DF8619" class="no-quick-link"></a>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 <%=vars.product_name%> 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](../../managing/management/jmx_manager_operations.html#topic_263072624B8D4CDBAD18B82E07AA44B6) for details on these security properties.

## <a id="concept_3B9C6CE2F64841E98C33D9F6441DF487__section_C69A2711A7664A9091A5E634221053CB" class="no-quick-link"></a>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](useful_gfsh_shell_variables.html#concept_731ECA5E40E943CBA5C1198A0745D8EE) for more information.

## <a id="concept_3B9C6CE2F64841E98C33D9F6441DF487__section_BE7FB8B355E748FA8BEFE75B2C3CB86E" class="no-quick-link"></a>Configuring gfsh Session Logging

By default, `gfsh` session logging is disabled. 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:

``` pre
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](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:

``` pre
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:

-   **&lt;locator\_name&gt;.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 .
-   **&lt;server\_name&gt;.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.

## Viewing Standard Output and Standard Error

By default, <%=vars.product_name%> 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
```


## <a id="concept_3B9C6CE2F64841E98C33D9F6441DF487__section_jcs_ltx_n4" class="no-quick-link"></a>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:

``` pre
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](getting_started_gfsh.html#concept_45D28CC9710C4EAFB6EECFA0D651D439__p_sb2_ttx_n4).

## <a id="concept_3B9C6CE2F64841E98C33D9F6441DF487__section_72323A45E0064FD2982663F7AC2A2E07" class="no-quick-link"></a>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.

## <a id="concept_3B9C6CE2F64841E98C33D9F6441DF487__section_C84414FF16AB4279A43A41C6C8B61A7E" class="no-quick-link"></a>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 <%=vars.product_name%> 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 <%=vars.product_name%> 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 disable 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.

See [Configuring gfsh Environment Variables](#concept_3B9C6CE2F64841E98C33D9F6441DF487__section_C69A2711A7664A9091A5E634221053CB).