---
title:  connect
---

<!--
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.
-->

Connect to a JMX manager either directly or via a locator.

<a id="concept_C2DCEE6743304549825C9B62E66DBADF__section_C27BE964CE554180A65968DBEBF50B23"></a>
If you are connecting via a locator, and a JMX manager does not already exist, the locator starts one.

gfsh connects as a discovery client to the locator service and asks where the JMX Manager is. The
locator knows when there is no member currently configured as the JMX manager and simply starts up
the JMX manager service within itself. gfsh connects as a JMX client to the locator's JMX RMI port.

You can also connect to a remote locator using the HTTP protocol, as illustrated by the second example below.

You can use this version of gfsh to connect to the JMX manager of Geode version 1.10 or newer. If a command
is not supported by the JMX manager to which it is connected, the command will fail with a detailed error message.

**Availability:** Offline. You will receive a notification "Already connected to: host\[port\]" if you are already connected.

**Syntax:**

``` pre
connect [--locator=value] [--jmx-manager=value] [--use-http(=value)?] [--url=value]
    [--username=value] [--password=value] [--token=value]
    [--key-store=value] [--key-store-password=value]
    [--trust-store=value] [--trust-store-password=value] [--ciphers=value]
    [--protocols=value] [--security-properties-file=value] [--use-ssl(=value)?]
    [--skip-ssl-validation(=value)?]
```

<a id="concept_C2DCEE6743304549825C9B62E66DBADF__table_B25D38C67FA047EB8F00A521573F1375"></a>

<table>
<caption><span class="tablecap">Table 1. Connect Parameters</span></caption>
<colgroup>
<col width="33%" />
<col width="34%" />
<col width="33%" />
</colgroup>
<thead>
<tr class="header">
<th>Name</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td><span class="keyword parmname">&#8209;&#8209;locator</span></td>
<td>Network address of the Locator in the form: <code class="ph codeph">host[port]</code>.</td>
<td><code class="ph codeph">localhost[10334]</code></td>
</tr>
<tr>
<td><span class="keyword parmname">&#8209;&#8209;jmx-manager </span></td>
<td>Network address of the JMX manager in the form: <code class="ph codeph">host[port]</code>.</td>
<td> </td>
</tr>
<tr>
<td><span class="keyword parmname">&#8209;&#8209;use-http</span></td>
<td><b>Deprecated: inferred by the presence of --url.</b> Connects to a JMX manager HTTP service using the HTTP protocol.</td>
<td></td>
</tr>
<tr>
<td><span class="keyword parmname">&#8209;&#8209;url</span></td>
<td>URL used to connect to a JMX manager's HTTP service.</td>
<td></td>
</tr>
<tr>
<td><span class="keyword parmname">&#8209;&#8209;username</span><br /><span class="keyword parmname">&#8209;&#8209;user</span></td>
<td>The user name of the credential to use in authentication when connecting
to the JMX manager.
When specified, if the <code>--password</code> option is not also specified,
<code>gfsh</code> will prompt for the password.
This option cannot be used with <code>--token</code>.
</td>
<td> </td>
</tr>
<tr>
<td><span class="keyword parmname">&#8209;&#8209;password</span></td>
<td>The password portion of the credential to use in authentication 
when connecting to the JMX manager.
This option cannot be used with <code>--token</code>.
</td>
<td> </td>
</tr>
<tr>
<td><span class="keyword parmname">&#8209;&#8209;token</span></td>
<td>The OAuth token to use in authentication
when connecting to the JMX manager. This token will be given to
<code>SecurityManager.authenticate</code> on the JMX manager.
This option cannot be used with <code>--user</code> or <code>--password</code>.
</td>
<td> </td>
</tr>
<tr>
<td><span class="keyword parmname">&#8209;&#8209;key-store</span></td>
<td>Java keystore file containing this application's certificate and private key. If the<code class="ph codeph">                                         --key-store-password</code> parameter is not specified, gfsh prompts the operator for the password.</td>
<td> </td>
</tr>
<tr>
<td><span class="keyword parmname">&#8209;&#8209;key-store-password</span></td>
<td>Password to access the private key from the keystore file specified by <code class="ph codeph">--key-store</code>.</td>
<td> </td>
</tr>
<tr>
<td><span class="keyword parmname">&#8209;&#8209;trust-store</span></td>
<td>Java keystore file containing the collection of CA certificates trusted by this application. If the <code class="ph codeph">--trust-store-password</code> parameter is not specified, gfsh prompts the operator for the password.</td>
<td> </td>
</tr>
<tr>
<td><span class="keyword parmname">&#8209;&#8209;trust-store-password</span></td>
<td>Password to unlock the keystore file specified by <code class="ph codeph">--trust-store</code>.</td>
<td> </td>
</tr>
<tr>
<td><span class="keyword parmname">&#8209;&#8209;ciphers</span></td>
<td>SSL/TLS ciphers used when encrypting the connection. The default is &quot;any&quot;.</td>
<td> </td>
</tr>
<tr>
<td><span class="keyword parmname">&#8209;&#8209;protocols</span></td>
<td>SSL/TLS protocol versions to enable when encrypting the connection. The default is &quot;any&quot;.</td>
<td> </td>
</tr>
<tr>
<td><span class="keyword parmname">&#8209;&#8209;security-properties-file</span></td>
<td>The <code class="ph codeph">gfsecurity.properties</code> file for configuring gfsh to connect to the Locator/Manager. The file path can be absolute or relative to the current gfsh directory.</td>
<td> </td>
</tr>
<tr>
<td><span class="keyword parmname">&#8209;&#8209;use-ssl</span></td>
<td>Whether to use SSL for communication with Locator and/or JMX Manager. If set to <code class="ph codeph">true</code>, the connect command also reads <code class="ph codeph">gfsecurity.properties</code>. SSL Options take precedence over values set in the properties file. If none are specified, defaults are used.</td>
<td><ul>
<li>If the parameter is not specified: <code class="ph codeph">false</code></li>
<li>If the parameter is specified without a value: <code class="ph codeph">true</code></li>
</ul></td>
</tr>
<tr>
<td><span class="keyword parmname">&#8209;&#8209;skip-ssl-validation</span></td>
<td>When SSL communication is enabled and this option is specified or assigned the value <code>true</code>, this gfsh client accepts any SSL certificate, allowing this gfsh client to authenticate any locator or server to which it is connecting. This option exists to facilitate testing, and it is not intended for production systems.</td>
<td>
<code>false</code>
</td>
</tr>
</tbody>
</table>

<span class="tablecap">Table 1. Connect Parameters</span>

**Example Commands:**

If you do not specify a locator or JMX manager, `gfsh` connects to the locator on the localhost at the default port.

``` pre
gfsh>connect
```

**Sample Output:**

``` pre
gfsh>connect
Connecting to Locator at [host=localhost, port=10334] ..
Connecting to Manager at [host=GeodeStymon, port=1099] ..
Successfully connected to: [host=GeodeStymon, port=1099]
```

**Example of connecting to a remote locator over HTTP:**

``` pre
gfsh>connect --url="http://myLocatorHost.example.com:8080/geode-mgmt/v1"
Successfully connected to: Geode Manager's HTTP service @
http://myLocatorHost.example.com:8080/geode-mgmt/v1
```

**Error Messages:**

``` pre
"Locator could not find a JMX Manager";
"jmx password must be specified.";
"Could not connect to : {0}. {1}";
"Could not find a Geode jmx-manager service running at {0}.";
"--token requires a value, for example --token=foo";
"--token cannot be combined with --user or --password";
"Could not connect to Geode Locator service at {0}."
```